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Preface 


This book describes the internal logic of the catalog management routines and 
provides diagnostic information. This information is directed to maintenance 
personnel and development programmers who require an in-depth knowledge of 
the program’s design, organization, and data areas. It is not required for effective 
use of catalog management facilities. 


You should be familiar with general programming techniques, OS/VS concepts 
and use, and System/370 before reading this book. If you are unfamiliar -with 
the general concepts of catalog management, read: 


OS/VS Data Management Services Guide , GC28-3783, for the general 
concepts of data sets and catalog management. 


OS/VS VSAM Programmer’s Guide, GC26-3806, for the general concepts of 
VSAM data sets and catalog management. 


OS/VS Utilities , GC35-0005, for information about IEHPROGM and 
generation data groups. 


OS/VS Data Management for System Programmers, GC28-0631, to see how 
catalog-management routines are invoked. 


Other books that may be helpful to you are: 


OS/VS!I Debugging Guide, GC24-5093, which describes how to analyze a 
main storage dump from OS/VS1. 


OS/VS2 Debugging Guide , GC28-0632, which describes how to analyze a 
dump from OS/VS2. 


OS/VS Service Aids, GC28-0633, which describes several service aids and 
programs available under the operating system (notably for this book, 
HMASPZAP). 


OS/VS DADSM Logic, GY26-3787, which provides details about module 
IGG0553A and rotational positioning support (RPS). 


OS/VS SAM Logic, GY26-3788, which provides details about the BLDL 
routine. 


OS/VS VSAM Logic, SY26-3805, which provides the internal logic of the 
VSAM Catalog routines, and describes the VSAM parameter list. 


OS/VS! System Data Areas , SY28-0605, which shows the content of most of 
the operating system control blocks and tables. 


OS/VS2 System Data Areas, SY28-0606, which shows data areas for OS/VS2. 


This book is divided into six chapters and a glossary: 


“Introduction” describes what the catalog is, how the catalog is structured, 
and how the catalog-management routines are invoked. The chapter defines 
terms that are used throughout the book. 


‘““Method of Operation” provides the design overview. This chapter describes 
the philosophy behind the programs. Emphasis is on the flow of data and the 
concepts of catalog management, rather than on the organization of the 
modules. 
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‘Program Organization”’ describes each module of catalog management and 
identifies the specific function that each performs to achieve the catalog 
management objectives. This chapter shows the logical flow from module to 
module and contains the flowcharts of the modules. 


‘Microfiche Directory’ contains a table that relates the information in this 
book to the listings on microfiche. > 


‘Data Areas’ describes the record formats and work areas that are used by 
catalog management. 


“Diagnostic Aids” can help you when you’re diagnosing a problem. This 
chapter shows how to dump and analyze the catalog, and how to determine 
what modules are used for a particular case. 


‘““Glossary” of terms and acronyms used in this publication is found just before 
the index. 
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Summary of Amendments 


VSAM capability is added. Three new modules (IGC0002F, IGGOCLCA, and 
IGGOCLCB) comprising Controller II, route catalog management requests to the 
appropriate catalog when both the OS/vVS and VSAM catalogs are present. 
Controller I is present in the one-catalog environment (OS/VS only). 


The initial load of both controllers is named IGC0002F. 


If you are using Release 1 of OS/VS1 at this time, then ignore all changes that 
reflect VSAM capabilities. 
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Introduction 


SYSCTLG Data Set 


Names and Indexes 


Catalog management is the part of OS/VS that enables a user to locate a data set 
by specifying only a data set name. Catalog management stores data set names 
with volume and device information in a catalog, itself a data set named 
SYSCTLG. In use, the name in the user’s request is correlated with the 
appropriate volume identification. The catalog-management routines organize the 
catalog by inserting, removing, and locating entries in the catalog, and by 
formatting new catalogs. 


Catalog management is a type 4 Svc. Under VS1, the catalog-management 
routines execute in the 1024-byte transient areas of the operating system nucleus. 
Under vS2, these routines execute in the Link Pack Area. System and machine 
requirements, therefore, are those of the operating system. 


This chapter discusses the catalog, illustrates several examples of a catalog, and 
discusses how the catalog-management routines are invoked. 


The catalog is always named SYSCTLG; thus, there can be only one OS/VS 
catalog on any one volume. 


SYSCTLG data sets are formatted like partitioned data set (PDS) directories. Each 
physical block consists of an 8-byte key and a 256-byte data record. The format 
of the logical records contained in the physical block is shown in the chapter 
“Data Areas,” page 61. 


Every cataloged data set has a name; this name can be a simple name or a 
qualified name. 


A simple name is a collection of up to eight EBCDIC characters. A qualified 
name is a String of names, separated by periods. The last name in the string is a 
simple name; the preceding names are qualifiers. Each qualifier can be up to 
eight characters long; the maximum total length of a qualified name is 44 
characters, including the separating periods. 


Each qualifier of a data set name corresponds to one index in the catalog. The 
structure of these indexes forms the catalog. The simple name of a data set is 
found in the lowest level of structure corresponding to the fully qualified name. 
The highest level of the catalog is called the volume index; the volume index is 
automatically built the first time a new catalog is used by the catalog 
management routines. 


Names in an index level are arranged in EBCDIC collating sequence. 


Each physical block of SYSCTLG can contain only one index level. An index 
level, however, can span more than one block. Multiple blocks of one index are 
chained together with the last logical record in each block. Contiguous blocks 
make use of the key to speed searching. 


Figure 1 shows an example of a catalog containing only the volume index and 
one simple name. (We will build on this figure throughout this chapter.) As with 
any data set on a direct access volume, SYSCTLG is found by tracing through the 
Volume Label to the Volume Table of Contents (VTOC). The VTOC contains a 
Data Set Control Block (DSCB) for each data set on that volume (independent of 
whether that data set is cataloged). The Format 1 DSCB for SYSCTLG points to 
the catalog data set. 
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The catalog data set is shown as the shaded block in Figure 1. The first record 
of SYSCTLG contains the volume index. The entry in that volume index identifies 
the device type and serial number for the volume that contains the data set 
ALPHA. 


Figure 2 shows a qualified name in the catalog. Cataloging the data set BETA.B.C 

adds another entry to the volume index. This entry points to the BETA index, ed 
which contains an entry for B. Following the pointer to the B index, we find an 

entry for C, which identifies the volume containing data set BETA.B.C. 


DSCB to 
SYSCTLG 
Data Set 


Device Type and 
Serial No. of 
Volume Containing 
Data Set ALPHA 


Figure 1. Example of a Catalog with One Simple Name J 


‘| Address of 
‘| first Block of 


SYSCTLG rae oe 


~ 4 Device Type and 
Serial No. of 
Volume Containing 
Data Set BETA.B.C 


Figure 2. Example of a Catalog with a Qualified Name 
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Control Volumes 


Aliases 


Any direct access volume supported by OS/VS may contain a catalog. A volume 
that contains a catalog is called a control volume (CVOL). The system residence 
volume always contains a catalog. 


A user specifies which CVOL contains the catalog (perhaps by allowing the 
default to the system residence volume). For a data set to be available through 
the catalog, its name must appear in either the catalog on the specified CVOL or 
in a CVOL that is connected to the specified CVOL. When a CVOL is connected, 
there is a pointer in the volume index of the catalog on the specified CVOL. This 
identifies the connected CVOL and names a high-level index on the connected 
CVOL. 


A search for a data set may start on the system residence volume; a CVOL 
pointer on the system residence volume can direct the search to a connected 
CVOL. The search starts again on the connected CVOL, using the fully qualified 
name in the CVOL’s SYSCTLG data set. The search may alternately be started on 
a CVOL other than the system residence volume, as directed by the user. 


Figure 3 shows a CVOL pointer in the catalog. This CVOL pointer connects 
another CVOL to this catalog. In Figure 3, an entry for Y has been placed in the 
volume index. This entry identifies the volume that contains the name Y in the 
volume index of its catalog. 


i Address of first 

/'| block of Index 

1 | BETA, for which 
/ |X is an Alias 


SySCILG f 2 ae 
{he ee eee 


" Volume Jatraa BETA 
: Inde } 


Device Type and 
Ser. No. of 
Volume Containing 
Name "Y"' in its 


Volume Index 


Figure 3. Example of a Catalog with an Alias and a Connected CVOL 


An alias is an alternative name for the highest-level index in a qualified data set 
name. There can be as many as 255 aliases to the first component of a qualified 
name. 


Figure 3 also shows an alias entry. Here the name X is an alias for BETA, so an 
entry for X is placed in the volume index. The entry for BETA and the entry for 
X both point to index BETA. Note that only the high-level name can have an 
alias. 


Generation Data Groups 


A generation data group (GDG) is a collection of data sets that have a common 
external name, and that are related by the time sequence in which they were 
cataloged (that is, their generation). For example, a data set named 
LAB.PAYROLL(Q) refers to the most recent data set of the group; 
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LAB.PAYROLL(-1) refers to the second most recent data set, etc. The number in 
parentheses is called the relative number of a specific generation. 


The relative number relates to an absolute name for that generation of the data 
set. The absolute name is the simple name of the data set. The absolute name 
has the general form GnnnnvV mm, where nnnn is the generation number, and 
mm is the version number. The last qualifier in a relative GDG name is the 
name of the generation index. The generation number in the absolute name is 
complemented before the name is added to the generation index, so the most 
recent name (highest generation number) is the first entry in the index. 


Figure 4 shows a generation data group in the catalog. In this example, the 
external data set name BETA.B.F applies to a generation data group, consisting of 
generations of the same data set. Here the lowest qualifying name, F, does not 
point to the data set, but rather points to the generation index. This generation 
index consists of pointers to generations of the data set group BETA.B.F. 


Entries of a Catalog 


The logical records of the SYSCTLG data set are called entries. These entries are 
linked together to form indexes and to connect indexes together. Figure 5 shows 
and names each type of entry. 


Each index contains one control entry and any number of pointer entries. The 
control entry, which is the first entry on each index, identifies that index. Other 
index entries link blocks of one index together, point to lower indexes, and point 
to data sets. 


SYSCTLG 


ALPHA || eer | ies IY | | 
Fe cee et eee /\ Address of First 


Index y Block of Generation 
BETA B / Index (Index F) 
/ 
oo / Y “7 — 
' 1 I SS ay ” 


z ‘ 
A eee eee 


eee |soponvoo | Ei ae 7 GO0O0IV00 a) a Sg, 


Device Type and 
Serial No. of 
Volume Containing 


Device Type and 
Serial No. of 


Volume Containing 
Most Recent 
Generation of Data 
Set BETA.B.F 


Oldest Generation 
of Data Set 
BETA.B.F 


Figure 4. Example of a Catalog with a Generation Data Group 


14. OS/VS Catalog Management Logic 
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Entry Name 


Alias entry 


Control volume 
pointer entry 


Data set pointer 
entry 


Generation index 
pointer entry 


Index control 
entry 


Index link entry 
Index pointer 
entry 

Volume control 


block 


Volume control 


block pointer entry 


Volume index 
control entry 


Abbreviation 
AE 


CVPE 


DSPE 


GIPE 


ICE 


ILE 


IPE 


VCB 


VCBPE 


VICE 


Description 


Contains an alternate name for the high-level 
qualifier of a data set name. 


Connects another control volume (CVOL) to this 
CVOL; contains a name that appears in the volume 
index of the connected CVOL. 


Contains the simple name of a data set and 
provides the location of this data set. 


Points to the lowest index for a generation 
data group. 


First entry of all indexes other than volume index; 
describes the index level for one qualifier of a data 
set name. 


Links this block to the next block in a chain of 
blocks for one index. 


Points to a lower-level index of this name. 


A block of the catalog that contains the volume 
list for a data set that resides on more than five 
volumes. 


Points to a volume control block. 


The first entry in the volume index (the 
highest-level index in the catalog); describes the 
volume index and controls allocation of space in 
the catalog on one volume. 


Figure 5. Kinds of Entries in the Catalog 


Using the Catalog Management Routines 


Catalog management routines are invoked by the utility IEHPROGM, the job 
scheduler, the Time Sharing Option (TSO) of the operating system, or by macro 
statements in an Assembler language program. 


IEHPROGM creates and deletes indexes, aliases, and generation indexes, and it 
catalogs and uncatalogs data sets according to specifications supplied by the user 


of IEHPROGM. 


The job scheduler calls the catalog management routines when it must locate a 
data set, given only its name, or when the DISP parameter of a DD statement 


implies catalog action. 


Dynamic allocation with TSO locates old data sets and catalogs new data sets. 
TSO command processors also call the catalog management routines to 
manipulate the catalog. 


All of these invocations of catalog management are produced by using three 
macro instructions: LOCATE, CATALOG, and INDEX. These macros generate a 
reference to a parameter list (produced by the CAMLST macro) and an SVC 26 


instruction. 


One of the operands of the CAMLST macro instruction specifies the function to 
be performed. These functions are categorized as locate functions or 
non-locate functions. The locate functions are those that require read-only 
operations to the catalog (that is, the catalog is not changed). The non-locate 
functions are those that do require changes to the catalog. 
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The locate functions are: 

e NAME, which locates a data set by name. 

e BLOCK, which locates a block of SYSCTLG. 

The non-locate functions are: 

e BLDX, which creates one index level. 

e BLDG, which creates a generation index. 

e BLDA, which assigns an alias to an existing high-level name. 
e DLTX, which deletes one index level. 

e DLTA, which deletes an alias. 

e LNKX, which connects a CVOL. 

e DRPX, which disconnects a CVOL. 

e CAT, which adds a data set name to the catalog. 


e CATBX, which adds a data set name to the catalog and creates any missing 
index levels. 


e UNCAT, which removes a data set name from the catalog. 


e UCATDX, which removes a data set name from the catalog and deletes index 
levels that are no longer needed (except the high-level index). 


¢ RECAT, which recatalogs a data set. 


For more information about the use of a catalog, see OS/VS Data Management 
for System Programmers, GC28-0631 (the first chapter), or OS/VS Utilities, 
GC35-0005 (the section on IEHPROGM). 


For more information about generation data groups, see OS/VS Data 
Management Services, GC28-3783. 
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Nethod of Operation 


Operation I, Read 


This chapter explains the design of catalog management. 


In its simplest form, catalog management consists of three operations: read, 
setup, and write. Figure 6 illustrates this overview. Input to catalog management 
is shown in the block on the left, processing is shown in the center block, and 
output from catalog management is shown in the block to the right. The three 
operations are shown in the process block. 


VS input to catalog management consists of a parameter list built by the caller 
with the CAMLST macro instruction, supervisor control blocks, and the existing 
catalog. The output from catalog management depends on the requested 
function. Locate functions result in a volume list returned in the caller’s area. 
Non-locate functions result in an updated catalog. 


VSAM input consists of a similar parameter list. For a description of the VSAM 
parameter list, see the chapter ‘““Data Areas” in OS/VS VSAM Logic, SY26-3805. 


When only the OS/VS catalog is present, catalog management, specifically 
Controller I, translates the VSAM input into CAMLST form. VSAM Superlocate, an 
internal Scheduler interface, is the only valid translatable list in Controller I. 
Output is translated to VSAM format. 


When both the OS/VS and VSAM catalog are present, Controller II directs activity 
to the appropriate catalog and translates as required. Duplicate entry checking is 
always done to prevent a catalog entry from existing in both the OS/VS and 
VSAM catalog. 


For a locate function, only the read operation is required. For a non-locate 
function, the read operation is used to locate the catalog block to which a change 
is to be made. The setup operation determines how the change is to be made, 
and the write operation updates the catalog accordingly. 


The CATBX function is slightly more complex; it requires that setup and write be 
executed several times. I'll discuss that function in more detail after describing 
each of the operations. 


Figure 7 illustrates the concepts of Operation I, Read. The input is that shown 
earlier in the overview. The caller’s parameter list includes a function request, 
points to a data set name, and identifies the CVOL to use (possibly the system 
residence volume by default). If a function is a locate function, an area in the 
caller’s module is made available for use as a return buffer. The usual SVC 
linkage for a type 3 SVC or type 4 SVC (catalog management is a type 4 SVC) 
provides pointers to several system control blocks. The VTOC of the CVOL is 
read to find the SYSCTLG data set and open it. 


Operation I begins by routing—actually pre-processing—the request to the OS/VS 
or VSAM catalog. 


In a one-catalog system, OS/VS only, VSAM Superlocate requests are translated 
and honored by Controller I. 
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In a two-catalog system, OS/VS and VSAM, Controller II routes locate-by-name 


requests as follows: 


# of Start 
Cilgs Parm Crlg 
Case to Search List Search 
0 2 OS/VS VSAM 
1 2 VSAM VSAM 
2 I OS/VS VSAM 
3 1 VSAM VSAM 
4 2 OS/VS OS/VS 
6 | OS/VS OS/VS 


The case is determined by the decimal equivalent of the last three bits in 
CAMOPTN3 of the CAMLST (see page 67). Note that the CAMLST macro 
instruction sets these bits to zero, corresponding to case zero. 


Non-locate requests are recognized by Controller IJ when the case bits are set to 
0, 1, 3, and 6. The parameter list passed to the controller determines which 
catalog the request will be routed to; however, duplicate entry checks are made 
in the opposite catalog on all catalog-type requests. 


Operation I continues by initializing a work area named WORKAREA. The data 
set SYSCTLG is opened by constructing a data control block (DCB) and a data 
extent block (DEB), which are shown as intermediate results in Figure 7. The 
BLDL macro instruction uses the DCB and DEB to read blocks of the catalog. The 
components of the name are isolated, and the high-level name is used as the 
search parameter of BLDL. BLDL begins by reading the block that contains the 
entry for the high-level name. 


If the entry that is found is a CVOL pointer entry, the current CVOL is closed and 
the CVOL identified by the pointer is opened. The process repeats until the 
appropriate CVOL is open. 


If the entry points to a lower level of the index structure, BLDL is called with the 
next component of the data set name as a search parameter. This process is 
repeated until the volume list is read (for locate functions), or the last valid level 
of the structure is found (for non-locate functions). 


Insert A in Figure 7 shows how the blocks of the catalog are chained together 
and how keys are used in this chaining process. The blocks are visualized in this 
insert as several contiguous blocks in the catalog, with block addresses ascending 
from left to right. The last entry of any catalog block is the index link entry 
(ILE), which is used to chain one block of an index to the next block in the same 
index. When two blocks are chained together but are not contiguous, as in the 
case of the first and fourth blocks in the insert for index A, the first block of the 
pair has a key equal to X‘FFFFFFFFFFFFFFFF’. BLDL issues a “‘search key 
high-or-equal” operation to the direct access device. When searching 
non-contiguous blocks, the high value of the key causes each block to be read 
and scanned for the requested name. 


However, when two blocks are chained together and are contiguous, as is the 
case with index B with the second and third blocks of the insert, the first block 
of the pair has a key equal to the name in the next-to-last entry of that block. 
The “search key high-or-equal’’ operation stops on such a block only if the 
requested name could be in it; otherwise, the search continues with the next 
contiguous block. 


Available blocks (that is, blocks that are unused) have a key equal to 
X‘0000000000000000’. Thus an available block of the catalog can be found by 
searching for a zero key. 
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Input Entered Via Process Output 
SVC 26 


wallet pees Locate Functions Volume Identification Aki ages 
Or parameters— START ! Operation |—Read Only | for volume(s) that ceva 
VSAM bir M Lia (starting at IGGOCLCO) contain the requested | at is returned 
Parameter | set name, (see Figure 7) data set in the caller's 
List address and work area 


work area. 


Three super- Operation ||—Set-up 
visor control — (see Figure 8) 
blocks are used 

SVRB by: catalog 


management 


SYSCTLG 


Non-locate 


Operation I|l—Write Functions Only 


(see Figure 9) 


Previously 
existing catalog, 
SYSCTLG | data set SYSCTLG 


Locate Functions Non-locate Functions 


Processing Flow 


Primary Data 
Movement 


Secondary Data 
Movement 


Data Pointer 
or Chaining Link 


¢ CAMLST is described on page 67 

¢« SYSCTLG entries are described beginning on page 61 

e Figure 7 is found on page 20 

¢« Figure 8 is found on page 22 

e Figure 9 is found on page 23 

« CVT, TCB, and SVRB are described in OS Control Blocks , GC28-6628. 


Figure 6. Catalog Management Overview 
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Caller’s parameter list, 
built by CAMLST macro 
instruction 


Conventional type 4 
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Notes: 

« CAMLST is described on page 67 

e WORKAREA is described on page 68 

¢ BLDLAREA is described on page 72 

«CVT, TCB, SVRB, VTOC, DCB, and 
DEB are described in OS/VS System 
Data Areas, SY28-0605. 

« Figure 6 is found on page 19 


Figure 7. Operation I—Read 
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Process 


One block of SYSCTLG 
is read each time 
BLDL is called 


Output 


WORKAREA 


1 Initialize WORKAREA in cailer’s area 
for locate function and GETMAIN 
for non-locate. Also GETMAIN for 
BLDL area. 


addresses, flags, 
used by catalog 
management 
routines 


2 Open the contro! volume (CVOL). 
If step 3 finds a CVOL pointer, 
this volume is closed and OPEN 
is repeated on new CVOL. 


3 Use BLDL to search SYSCTLG 
for one level of name. If a pointer to a 
lower index is found, search it for the 
next level of name. Insert A shows how 
blocks are chained together. 


See Figure 6 — to relate this process block 
to overall Method of Operation 


A 


Contiguous blocks of SYSCTLG ————t 


PAYROLL 


Block of index 
B—last entry 
is named 
‘PAYROLL’ 


FFFF...FF 


Next block of 
index B 


Next block 
of index A 


Block of 
index A 


Next contiguous 

block is not for 

the same index as 

this block. This 

block’s key is 
X’FFFFFFFFFFFFFFFF’. 


Next contiguous 
block is for same 
index. This block’s 
key is the name 

of the last entry. 


° Operation I uses modules: 


IGCO002F pages 32 and 34 
IGGOCLCO page 40 
IGGOCLC1 page 42 
IGGOCLC2 page 44 
IGGOCLC3 page 46 


« Opening a CVOL uses modules: 
IGC0002H page 56 
IGGOCLF2 page 58 


u | 


Intermediate results, 


When locate function is 
requested and data set 
pointer is found, associated 
block of SYSCTLG is moved 
to caller’s area 


BLDL AREA 


Parameter list and 
input buffer for 
BLDL routine. 


Key 
9000...00 Ped 
; Data 
Available 
block of 
SYSCTLG 


The key of an unused 
block is a binary zero. 


Operation II, Setup 


Operation Hil, Write 


Figure 8 illustrates the setup operation. Input to this operation includes the name 
of an entry to be added or deleted from the catalog. This might be the simple 
name of a data set to be cataloged or removed from the catalog, or it might be 
an index name for a level to be created or deleted. Other information needed to 
build a new entry might be passed, depending on the request. The catalog block 
to which the change is to be made remains in a buffer from Operation I. 


The setup process consists of either naming an entry to be deleted or 
constructing a new entry, then copying the catalog block one entry at a time 
from an input buffer to an output buffer. The new entry is merged into collating 
sequence with the old entries, or the named entry is bypassed, depending on the 
request. 


Adding or deleting entries causes the following entries in the index to be 
displaced. For example, adding to a full block can result in an “overflow” of 
entries. These overflow entries must be added to the next block in the index 
chain. The effect of a change can thus ripple down the index chain. Similarly, a 
deletion can result in rippling in the other direction. 


Figure 9 illustrates the write operation. Input to the operation is an updated 
catalog block and a relative track address to which this block is to be rewritten 
into SYSCTLG. Rippling can cause several blocks to be rewritten. Finally, the 
block containing the index control entry (ICE) and the volume index control 
entry (VICE) are updated and rewritten to reflect the changes made to the 
catalog. Output is the updated catalog. 


The insert to Figure 9 shows how the CATBX function is performed. In this case, 
the index levels to which a data set name is to be added do not exist; these index 
levels must also be created. This is done from the bottom up. 


Step 1 shows the new data set pointer entry (DSPE) ready to be added to the 
catalog. A new index block is constructed and this DSPE is inserted into it. The 
newly constructed index block is written to the first available space in SYSCTLG, 
and the relative track address of that block is saved for step 2. The catalog is 
searched for another available space. 


In step 2, a new index pointer entry (IPE) is created for the index block written 

in step 1, using the relative track address from step 1. If the next higher level of 
the index structure is also missing, another index block is created and written to 

SYSCTLG. 


This process is repeated until a level is finally reached that does exist (step 3). 
An IPE is constructed for the highest new index and is added to the existing 
level. 


For example, if the data set name A.B.C.DATASET were added to the catalog 
when none of the index levels A, B, or C exist, then step 1 would build index 
level C with a DSPE for A.B.C.DATASET in it. Step 2 would first build index level 
B with an IPE for C in it, and then index level A with an IPE for B in it. Finally, 
step 3 would insert an IPE for A into the volume index. 
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Process 


Point to entry to delete or 
construct new catalog entry. 


Copy index block to output buffer, 
one entry at a time. Merge new 
entry into collating sequence (add 
function) or skip over named entry 
(delete function). Displacement 

of following entries can result 
in an update to the next index 


to overall Method of Operation 


tA 


~ 


Notes: 


e SYSCTLG entries are described beginning on page 61 
e BLDLAREA is described on page 72 
e Figure 6 is found on page 19 


¢ Operation II uses modules: 


IGGOCLC3 page 46 
IGGOCLC4 page 48 
IGGOCLCS page 50 
IGGOCLC6 page 52 


Figure 8. Operation II—Setup 
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Re-write block of SYSCTLG. 


Address (TTR) Changes to this block may ripple 
of block of a. to Following blocks of index 
ee yee chain; that is, a change to 
block is to be Following blocks might now be 
written setup (repeat Operation II). 
See Figure 6 — to relate this 
process to overall Method 


of Operation. 


Address (TTR) of next Used blocks are shaded Address (TTR) of next available Address (TTR) of next available 
available block of SYSCTLG Fille blocks are block of SYSCTLG block of SYSCTLG 
SYSCTLG 
SYSCTLG Address (TTR) of block Address (TTR) of block 
Data Set Pointer Entry for createc in step 1. created in step 2 


name to be cataloged 


Index Pointer Entry 
for block f for block 
created t created 


in step 1. in step 2. 


Next higher index 
level (also newly 
constructed block) 


Newly constructed 
index block for 
lowest level 


Step 1 since the lowest-level index does not exist, Step 2 an index pointer entry is built for the block | Step Finally a level is reached that does 
a new block is created and the data set name created in step 1 and inserted into the next higher exist. An index pointer entry is created to 
is cataloged into that block. The new block level. If that level does not exist, it too is created. insert into it. 
is written into the first available space in 
SYSCTLG, and its address saved for step 2. 


Notes: 
¢« Figure 6 is found on page 19. 
¢ SYSCTLG entries are described beginning on page 61. 


¢ Operation III uses modules: 


IGGOCLC3 page 46 
IGGOCLCS page 50 
IGGOCLC6 page 52 
IGGOCLC7 page 54 


Figure 9. Operation 11]—Write, with CATBX Detail 


Program Organization 


This chapter discusses the implementation of the catalog management routines, 
showing how the actual modules fit together. 


The final authority of any program is the assembly or compilation listing. These 
module discussions complement the assembly-listing comments, and assume that 
the listings are at hand. You should have them available for any in-depth 
analysis. 


Overall Organization 


The three operations described in the previous chapter, ‘‘Method of Operation,”’ 

form a conceptual image of catalog management. In reality, the broad operations 
of read, setup, and write merge together somewhat when packaged into modules. 
Still, the concept is useful, and it is continued in this chapter. 


There are 11 or 13 modules in catalog management, depending on whether 
Controller I or Controller II is present. Eight modules and the controller form 
three phases, and two of the modules provide auxiliary services used by any 
phase. 


Phase I equates to the read operation. It performs locate functions and the 
corresponding part of non-locate functions. Phase I consists of: 


| e« Controller I or II, which routes the catalog management request to the 
appropriate routines. (This module does not exist in OS/VS1 Release 1.) 


e IGGOCLCO, Initialization, which initializes work areas and opens the CVOL. 
(This module is named IGC0002F in OS/VS1 Release 1.) 


e IGGOCLC1, Relative GDG and Alias, which resolves aliases and relative GDG 
numbers. 


¢ IGGOCLC2, Locate, which searches the lower levels of the index structure. 


Phase II begins the setup operation. It checks the validity of the requests against 
the existing entries in SYSCTLG, and it builds new entries to be added or it 
names entries to be deleted. Phase II consists of: 


e IGGOCLC3, Update Initialization and Entry Building, which begins the update 
process by building new index blocks and routing the request as needed. 


« IGGOCLC4, Entry Building, which builds data set pointer entries to add to the 
last valid level of the index. 


Phase III completes the setup operation and performs the write operation. It 
merges entries into SYSCTLG blocks, deletes entries from blocks, and does most 
of the writing that is needed. Phase III consists of: 


e IGGOCLCS, First Load of Update, which frees index blocks, frees volume 
control blocks (VCBs), and writes new VCBs. 


¢ IGGOCLC6, Second Load of Update, which updates blocks, writes updated 
blocks to SYSCTLG, anu ripples the change as needed to the last block of the 
updated chain. 


¢ IGGOCLC7, Third Load of Update and Error Handling, which writes the last 
updated block, updates the control entries, returns control to IGC0002F (to the 
caller, in OS/VS1 Release 1), and also handles error conditions. 
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The two service modules are: 


¢ 1GC0002H, SYSCTLG Open/Extend, which opens the SYSCTLG data set or gets 
the next extent of that data set, when needed. 


e IGGOCLF2, SYSCTLG and BPAM Directory Formatter, which formats a new 
catalog and any new extents of a catalog. } 


| Each of these modules operates in a transient area. 1GC0002F, the entry point for 
catalog management, is invoked by a caller with an SVC 26; control is passed to 
the other eight modules of the phases via an XCTL macro instruction. 1GC0002H, 
one of the service modules, is invoked via an SVC 28; it passes control to 
1GGOCLF2 via an XCTL macro instruction. 


Figure 10 shows the organization of modules with relation to the phase structure . 
and illustrates the overall flow of control from one module to another. 
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VSAM Catalog Management. 
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|GCO0002F — 
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Catalog Management 


Reentry for additional processing 
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SVC3 e@ Resume processing of 
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e Reformat VSAM output to OS/VS. % 
SVC 3 
Return 
to Caller IGGOCLCB— 


@ Resume processing of VSAM 


requests. 
® Reformat OS/VS output to VSAM. 


svc 3 
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IGGOCLCO 


XCTL 


IGGOCLA1 
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| Figure 10. (Part 1 of 2) Overall Program Organization 
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Phase | 


|\GGOCLCO-— Initialization Other 
@® (Initialize workareas. 


Alias or 


BLDA, LNKX 


@ Open given CVOL. 
e Search for high-level-name. 


IGGOCLC1—Relative GDG and Alias 


® Resolve alias. 
e Construct BLDA or LNKX entry. 
e Process relative GDG. 


Al! modules go to 
IGG@CLC7 on error 
condition (paths 
not shown here). 


|GGOCLC2—Locate 


Relative GDG 
®@ Search lower levels of name. 
@ Save last valid level of index. 


Return to 
{GC0002F e Relocate CCWs. 


XCTL Locate Functions 


Non-locate 
Functions 


Return to. 
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and Entry Building 

© Ensure tnat VICE, ICE, and UCATDX with blocks to free 

Space present. CATBX, CAT, 

e Construct and write new index block.| REGAT 
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VCBs to be written 
or VCB or Index blocks 
to be Freed. 


IGGOCLC4—Entry Building 


e Construct new DSPE or VCBPE. 
e Scratch GDG if needed. 


SVC 28 


zx Phase III 
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® Set ‘Must Complete’ on. Not 
@ Free VCBs or index blocks. CATBX 
e Write VCBs. 
e Perform EMPTY option as needed 


|GGOCLC6—Second Load of Update 
® Add or delete entry from 


|GGO002H—Open/E xtend 
@ Build OCB/DEB. 

Call |GGO553A for new extent 
Cail |GGOCLF?2 to format 

new SYSCT LG’ 


index block. 
e Ripple as needed 


IGGOCLC7- Third Load of Update 
and Error Handling 
@ Write last index block. 
e Update ICE and VICE. 
e Write environment record for 
error condition. 
@ Set return code 
Return to 


Catalog Mgt. 1G COQ002F 


SVC 3 | XCTL 


IGGOCLF2—SYSCTLG and BPAM 
Directory Formatter 


@ Format extent. 
@ Initialize VICE block. 


Return to 
Catalog Mgt. 


svc 3 


| Figure 10. (Part 2 of 2) Overall Program Organization 


An SVC 26 invokes the catalog management routines; control is then passed to 
IGC0002F, the catalog controller. The path that occurs through the remaining 
modules depends on both the particular function that is requested and the entries 
that are found in the catalog. 
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Each block in Figure 10 represents a module of the catalog management routines 
and contains a brief description of the functions that it performs. Each path is 
identified by the function/condition that it represents. 


For example, follow the path for a BLDX function (request to create an index 
level) on a VS catalog. Assume that part of the index structure already exists; 
that is, this request extends an existing index structure. ) 


Specifically, this is what each module does to accomplish the BLDX request: 


e Entry to catalog management is at IGC0002F, which routes the request to 
IGGOCLCO. 


e IGGOCLCO initializes work areas, opens the CVOL, and locates the high-level 
name of the index structure. The arrow labeled ‘‘Other’’ is the exit path for 
this example. 


e IGGOCLC2 locates the remaining levels of the existing index structure, to find 
the last valid level. The new index is to be added to that level. 


e BLDX is a non-locate function, so control passes to IGGOCLC3. This module 
reads the control entries (VICE and ICE), constructs an index pointer entry 
(IPE), and routes the request via the arrow labeled “‘Other.” 


e IGGOCLC6 inserts the new IPE into the index block left by IGGOCLC2. 
IGGOCLC6 writes the updated block to SYSCTLG, and ripples the effect of the 
change down the index chain, if necessary. The last block of the chain is left 
in the input/output buffers, but it is not written to SYSCTLG. 


e IGGOCLC7 writes the last block of the updated index chain, then reads, 
updates, and rewrites blocks containing the index control entry (ICE) and 
volume index control entry (VICE). Resources are released and control passes 
back to IGC0002F for return to the caller. 


Traces such as the one just discussed are illustrated in the chapter ‘Diagnostic 
Aids” as an aid in identifying the modules involved in any particular situation. ) 


All of the VS catalog management modules are re-entrant. They use a common 
work space, initialized by IGGOCLCO and called WORKAREA. (WORKAREA is 
described on page 68.) 


Macros and Services Used 


A small set of macros and services is used throughout the catalog management 
routines. The prologue commentary for each module lists the specific ones used 
in that module; the complete set is: 


e BLDL, the routine used by Phase I to read blocks of SYSCTLG, which is 
formatted like a partitioned data set (PDS) directory. It is accessed through 
entry point IECPBLDL, whose address is found in field CVTPBLDL of the 
Communication Vector Table (CVT). In Phase I catalog management routines, 
this routine is used in a closed subroutine labeled ““CALLBLDL’’. 


e IECPCNVT, a routine used to convert relative track addresses to absolute 
addresses. It is accessed through entry point IECPCNVT, whose address is 
found in field CVTPCNVT of the CVT. In the catalog management routines, 
this routine is used in the closed subroutine labeled ‘‘TOABSL’’. 


e IECPRLTV, a routine used to convert absolute track addresses to relative 
addresses. It is accessed through entry point IECPRLTV, whose address is 
found in field CVTPRLTV of the CVT. In the catalog management routines, this 
routine is used in a closed subroutine labeled ““TORLTV”’. 


e ENQ, a macro instruction used to control three resources: high-level name, 
volume index, and volume index control entry (VICE). J 
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Character Dependency 


Resource Enqueuing 


Register Usage 


e DEQ, a macro instruction used to release resources obtained by the ENQ 
macro. 


e EXCP, a macro instruction used for input/output operations in Phase II and 
Phase III modules. In the catalog management routines, this instruction is used 
in a closed subroutine labeled “‘IO’’. 


e EXIT, a SVC instruction used to return to the caller. 


e XCTL, a macro instruction used to pass control from one catalog management 
module to another. 


¢ GETMAIN, a macro instruction used to allocate main storage. It is used by 
catalog management to obtain work areas and input/output buffers. 


¢ WAIT, a macro instruction that allows an input/output operation to complete 
before continuing processing. 


e FREEMAIN, a macro instruction used to release main storage used for work 
areas by catalog management. 


e SCRATCH, a macro instruction used to delete a data set. 


e DSECT macros IEFUCBOB and CVT, which describe system control blocks. 


The modules of catalog management require that the character set used at 
execution time be equivalent to that used at assembly time. The IBM-supplied 
version of catalog management assumes EBCDIC character representations. If a 
different character set is to be used during execution, the modules must be 
re-assembled. The instructions involved in this dependency are identified by label 
in the prologue commentary of each module. 


Figure 11 shows when the resources of catalog management are enqueued in 
relation to the modules. Three resources are used: high-level name, volume 
index, and volume index control entry (VICE). To prevent an interlock between 
two callers, the high-level name is a/ways enqueued first, the volume index is 
enqueued second, and the VICE is enqueued last. 


The conditions of enqueuing are determined from the request. If the volume 
index is to be modified, then the volume index must be enqueued exclusively. 
Otherwise, it can be shared. If a locate function is requested, then the high-level 
name can be shared. If a non-locate function is requested, the high-level name is 
enqueued exclusively to protect all lower-level indexes under it. 


The major name for enqueuing is always “SYSCTLG’’. The minor name is the 
high-level name with the UCB address appended to it, ““SYSCTLG”’ with the UCB 
address appended to it, or zeros with the UCB address appended to it. 


With the exception of IGC0002H and IGGOCLF2, the catalog-management modules 
use a common set of registers. Module IGGOCLCO initializes these registers, and 
their contents remain throughout. Contents of registers not described are 
considered destroyed. 


Registers 


4 Base register for the module 

6 Base register for WORKAREA DSECT 

8 Base register for CAMLSTD DSECT 
12 Linkage register for BAL instructions 
14 Linkage register for BAL instructions 
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Locate Non-Locate 
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Order of enqueuing: 1. High-level Name 
2. Volume Index 
3. VICE (when applicable) 


VICE 


Missing combinations are error conditions 


Figure 11. Resource Enqueuing 
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Module Descriptions 


Each of the modules of catalog management is described in this section. The 
flowcharts are organized into two parts. Supporting text for the module appears 
beside each part. 


Error-condition tests are not shown on the flowcharts. An error condition results 
in a branch to label ERR xx , where xx is the appropriate error code. There the 
error exception code is set and an XCTL to IGGOCLC7 occurs. The labels on the 
flowchart are those used in the assembly listing. 
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IGCOOO2F: Controller | 


Note: This module does not exist in OS/VSI 
Release 1. 


IGC0002F is the entry point for the catalog 
management routines, which are invoked by 
an SVC 26. IGC0002F is also entered from the 
following modules via XCTL, for return to the 
caller: 


e IGGOCLCI1 
e IGGOCLC2 
e IGGOCLC7 


Registers 
On Entry via SVC 26: 


1 Address of caller’s parameter list 
3 Address of CVT 
4 Address of SVRB 


Functions 


This module contains references to VSAM for 
planning purposes only. The module routes a 
request for catalog management to IGGOCLCO 
without change when the caller is not VSAM. 
When the request is for a VSAM request, 
[GC0002F: 


1. Translates the VSAM parameter list into 
CAMLST form and invokes normal 
catalog management routines (XCTL to 
IGGOCLCO). 


2. Translates the results of the catalog 
search to VSAM format. 


Internal Subroutines 


STRTCNTL handles the initial entry into 
1GC0002F by determining what functions are 
requested. 


RESMCNTL handles subsequent re-entries of 
I[GC0002F by determining if further functions 
are needed to satisfy the request. 


FUNCT6 is used when the parameter list is 
already in the form of a CAMLST. 


FUNCT7 is used when the parameter list is in 
VSAM form. 


RESUME7 passes catalog information back to 
a VSAM caller, and controls further catalog 
searches when such is required. 


32 OS/VS Catalog Management Logic 


cae A A3 
Enter carey ed Type of Initial GETMAIN for 
Management or entry (test local 
reg 1) savearea 


Management routines. 


B2 B3 
Save regs ave 
returned trom iveorne bien 
ctlg mgt about request 


SVC 26 for initial entr Th 
XCTL from other catalog Reentry | 


S 3 
a STRTCNTL 
iS Pe a Determine 
function to be 
dt 


ROUTE = XCTL 


Restore Restore 
atria. | registers 
about atria. | 


Fl —_—— oe ao 
: XCTL (SVC 7) t EXIT (SVC 3) to 
STRTCNTL ctlg mgt ) caller 


G 


Locate 
request 


VSAM 
catalo 
reques 


revo 
Error 


| | | 
H1 H2 
FUNCT6 FUNCT? H3 
Prepare for Translate to RESMCNTL o] 
non-VSAM non-VSAM 
catalog request request 
J 


1 £ 
Return Translate 
results of 
locate 


Return 


OSPL translates a VSAM parameter list into a (res) (tm) 
FUNCT6 FUNCT? 
CAMLST. 
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contain SYSCTLG. possanes, (ren 
20 Syntax error in data set name. 
24 Permanent input/output error. 
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CVT, TCB, SVRB, DCB, DEB, and UCB are 

described in OS/VS! System Data Areas, 
SY28-0605, and in OS/VS2 System Data 

Areas , SY28-0606. 
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IGCOOO2F: Controller Il 


Note: This module exists only in OS/VS1 1GCOO02F 
Release 2, and it exists unless you specify 
“VSAM=EXCLUDE” in the CTRLPROG macro 
at system generation. 
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This module determines the type of request ) 


1 Address of caller’s parameter list 
3 Address of CVT 

4 Address of TCB 

5 Address of SVRB 


On Re-entry via XCTL: Restore 
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about request 


1 Negative number 
2 Return code 
12 Address of Controller’s work area 


Functions 


for catalog management and routes the 
request to the OS/VS (IGGOCLCO) or the 
VSAM (IGGOCLA1) catalog. 


This module is also the entry point for all 
returns from either catalog. It determines the 


2 
STRTCNTL 
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ocatle unction 
The calling of initial and resume functions is non-locate | Error _ 
based on the following: locate Function 3 
[non-locate_| Function 3 
# of Start locate Function 4 
Ctlgs Parm Cilg non-locate 
Case to Search List Search locate Function 6 
I a) VSAM VSAM None of the above 
2 OS/VS VSAM ol 
3 1 VSAM VSAM Return 
4 2 OS/VS OS/VS Cretan 
6 1 OS/VS OS/VS 


The case is determined by the decimal 

equivalent of the last three bits in CAMOPTN3 

of the CAMLST (see page 67). Note that the 

CAMLST macro instruction sets these bits to 

zero, corresponding to case zero. J 
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Internal Subroutines 


STRTCNTL handles the initial entry into 
IGG0002F to determine which function is 
required. 


RESMCNTL handles subsequent entries into 
1GC0002F and routes to the appropriate 
module for addition processing. 


FUNCTO routes OS/VS requests to the VSAM 
catalog for a two-catalog search. 


FUNCT2 routes directly to the VSAM catalog. 


FUNCT3 routes VSAM DEFINE requests to the 
OS/VS catalog for a duplication check before 
any action is taken. All other requests go 
directly to the VSAM catalog. 


FUNCT4 routes directly to the OS/VS catalog. 


FUNCT6 routes OS/VS CATLG requests to the 
VSAM Catalog for a duplication check before 
any action is taken. 


AMOPL translates a CAMLST into a VSAM 
parameter list. 


OSPL translates a VSAM parameter list into a 
CAMLST. 


For a description of the VSAM parameter list, 
see the chapter “‘Data Areas” in OS/VS 
VSAM Logic, SY26-3805. 


Exits 


Control passes via an XCTL macro instruction 
to: 


e IGGOCLCA 

e IGGOCLCB 

« [GGOCLCO 

e IGGOCLAI 
References 

Page 

Item number 
CAMLSTD 67 
IGGOCLCA 36 
IGGOCLCB 38 
IGGOCLCO 40 
Method of Operation Figure 7 20 


CVT, TCB, SVRB, DCB, DEB and UCB are 
described in OS/VSi System Data Areas, 
SY28-0605, and in OS/VS2 System Data 
Areas , SY28-0606. 
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Qoneet 
IGGOCLCA: Resume Processing of OS/VS Requests 


IGGOCLCA is the entry point. Control comes C reser) 
front: RESMCNTL 


e [GC0002F after determining which 7 locate || Resume 0 
catalog was originally requested. ae i. ne ) 


locate 


B2 
i non-locate | Error 
Registers eee {nor | - 
locales || Resume 4 


12 Address of @DATD [non-locate | Error 


locale Resume 6 
Functions ___|[non-locate [Error | 


: . 2 None of the above | Error 
This module determines the status of the RESME NITY . 
<8 . Determine which 3 
original request. It routes control to either RESUME Funct ton ( nent to ) 
Z ne ‘ : ; Caller 
catalog if additional processing is required and 


performs whatever conversions or translations 


are necessary. 
D3 
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Complete 
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O 
RESUME3 continues the processing of 
FUNCTION3 if the entry was not found in the 


OS/VS catalog. If the entry was found, F2 OSRD 

RESUME3 translates the return code. ( Sian oes ) getnEA Cade to 

OSPL translates a VSAM parameter list into a | 

CAMLST. 2 
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AMORD formats OS/VS information into the 
VSAM format. 


AMORC translates OS/VS return codes into 


A3 
VSAM return codes. ( Besunecd 


CNTL2CAT handles cases when there are more 
than 20 volumes in the volume list. 


Exits 


Request 


Entry Complete Translate VSAM 


Return Code to 
OS/VS 


Control passes via an XCTL macro instruction 
to either IGGOCLCO or IGGOCLAI or via an Bee 
EXIT SVC instruction to the caller. 
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IGGOCLCB: Resume Processing of VSAM 


IGGOCLCB is the entry point. Control comes 
from: 


e IGC0002F after determining which 
catalog was originally requested. 


Registers 
12 Address of @DATD 


Functions 


This module determines the status of the 
Original request. It routes control to either 
catalog if additional processing is required and 
performs whatever conversions or translations 
are necessary. 


RESMCNTL determines which resume function 
is required. 


RESUMEI continues the processing of 
FUNCTIONI if the entry was not found in the 
VSAM catalog. If the entry was found, 
RESUMEI performs the necessary 
OS/VS-to-VSAM conversions. 


olume List 
Area large 
enough 


Format OS/VS 
Data Set to 
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G 32 
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size and Return 


More 
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Requests 
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OS/VS catalog. If the entry was found, 
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OSPL translates a VSAM parameter list into a B 
CAMLST. 


AMORD formats OS/VS information into the 
VSAM format. 


AMORC translates OS/VS return codes into 
VSAM return codes. SAM Define 


Request 


CNTL2CAT handles cases when there are more 


than 20 volumes in the volume list. YES 


Exits 


D1 
; . . Set up XCTL for Entry foun 
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Return Code to 
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K3 
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IGGOCLCO: Initialization 


Note: This module is named IGC0002F in 
OS/VS1 Release 1. 


IGGOCLCO is the entry point. Control comes 
from IGC0002F. 

Registers 

On Entry: 


jomeh 


Address of caller’s parameter list 
(CAMLST) 

3 Address of CVT 

4 Address of TCB 

5 Address of SVRB 


On Exit: 


2 Address of UCB 
4 Base register for this module 
5 Pointer to SVRB extension 
6 Base register for WORKAREA DSECT 
8 Base register for CAMLSTD DSECT 
9 Address of CVT 
12 Linkage register for BAL instructions 
13. Base register for BLDLAREA 
14 Linkage register for BAL instructions 


Functions 


WORKAREA is the common workspace and 
communications area for all catalog 
management modules. When a locate 
function is requested, WORKAREA is built 
over the caller’s 265-byte area, and a second 
area (called BLDLAREA) is obtained by 
GETMAIN. BLDLAREA is used with the 
routine BLDL. 


When a non-locate function is requested, a 
larger area is obtained by GETMAIN for 
WORKAREA. Part of this area is used for 
BLDLAREA during execution of modules 
IGGOCLCO, IGGOCLC1, and IGGOCLC2. This 
portion of WORKAREA is redefined for use as 
input/output buffers thereafter. 


The first 256 bytes of WORKAREA are set to 
zero, which initializes all switches and flags. 
Supervisor addresses and the data set name 
go into WORKAREA, and the data set name is 
decomposed into its components. BLDLAREA 
is initialized for use as input/output buffers. 


The UCB table is searched for device 
information about the given CVOL. GETMAIN 
is used to allocate space for a DCB and a 
DEB, and 1GC0002H is used to open the CVOL 
(via an SVC 28). 
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eee fro 
Bac ae 


Bl 
Check address 
of caller's 
area for 
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GETWA CATMAIN 


GETMAIN for 
index/catalog 
function 


Function 
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ZEROWA 


Clear WORKAREA 
(set all flags 
to zero) 


equest to 
eae by 
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32 
d and store 
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Build elise 
Pe ee 
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Ue pacese 
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and construct 
table 


MOVEHIL 
K2= 


Separate out 
the magn: level 
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Note: The OPEN macro instruction is not 
used to open a CVOL. IGC0002H constructs a 
modified DCB/DEB for use by catalog 
management; 1GC0002H is described on page 
56. No CLOSE macro is issued to close a 
CVOL. FREEMAIN simply releases the main 
storage that is used for the modified 
DCB/DEB. 


The first component of the data set name is 
used as the search parameter for BLDL. 
Searching begins with the first block of 
SYSCTLG. If BLDL returns a CVOL pointer 
entry (and the request is not LNKX or DRPX), 
the current CVOL is closed and control goes 
back to label UCBSRCH (block A1). 


Internal Subroutines 


None. 


Exits 


Control passes via an XCTL macro instruction 
to: 


¢ IGGOCLC1 if requested function is BLDA or 
LNKX, or if the high-level name is an alias. 

e IGGOCLC7 for an error condition. 

e IGGOCLC2 otherwise. 


Control passes via an SVC 28 to IGC0002H to 
open the catalog, and returns to this module. 
Error Conditions 


Code Reason 


4 CVOL not mounted or does not 
contain SYSCTLG. 
20 Syntax error in data set name. 
24 Permanent input/output error. 
28 Bad relative track address for 
SYSCTLG. 

32 Bad address for caller’s area. 
References 
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CVT, TCB, SVRB, DCB, DEB, and UCB are 
described in OS/VS! System Data Areas, 
SY28-0605, and OS/VS2 System Data Areas , 
SY28-0606. 
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IGGOCLC1: Relative GDG and Alias 


IGGOCLC1 is the entry point. Control comes 
from: 


e IGGOCLCO when the requested function is 
either BLDA or LNKX, locate-by-block, or 
when an alias is found (except with a 
DLTA request). 


e IGGOCLC2 when a relative GDG number is 
found in the data set name. 


Registers 


4 Base register for this module 

6 Base register for WORKAREA DSECT 

8 Base register for CAMLSTD DSECT 
12 Linkage register for BAL instructions 
13. Base register for BLDLAREA 
14 Linkage register for BAL instructions 


Functions 


When locate-by-block is requested, the block 
is read and returned to the caller. 


When control comes from IGGOCLC2, control 
goes to label RELGDG for relative GDG 
processing. 


If the requested function is BLDA or LNKX, 
the appropriate entry is constructed and 
control passes to IGGOCLC2 for routine to the 
update modules. 


When an alias is discovered, the fully 
qualified name is reconstructed in the caller’s 
name area, using the true name. The name 
table is then updated to reflect the change 
and the high-level name is re-enqueued. 


Control comes from IGGOCLC2 when a 
relative GDG number is discovered in the data 
set name. This module determines the 
absolute GDG name for the data set. If the 
request is a locate function, either the volume 
list for the data set or a new absolute GDG 
name is returned to the caller. Otherwise, an 
error condition exists and IGGOCLC7 is 
invoked. 


The generation number in absolute GDG 
names is complemented before the names are 
added to the generation index. Therefore, the 
most recent entry (the highest generation 
number) is the first entry in the index, the 
second most recent entry is the second entry 
in the index, etc. 


When the relative GDG number is negative or 
zero, an absolute GDG name from the 
generation index is returned to the caller 
along with the corresponding volume list. 
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Zero corresponds to the first entry, -1 
corresponds to the second entry, etc. 


When the relative GDG number is positive, a 
new absolute GDG name is created and 
returned to the caller. If the generation index 
is empty, this name is GO00OnV00 (where n is 
the relative number). If the generation index 
is not empty, the relative GDG number is 
added to the generation number of the first 
entry to create the new absolute GDG name. 


Internal Subroutines 

CALLBLDL calls BLDL routine via entry point 
IECPBLDL. 

Exits 


Control passes via an XCTL macro instruction 
to: 


e IGC0002F after relative GDG processing. 
e IGGOCLC7 for error conditions. 


e IGGOCLC2 otherwise. 


Error Conditions 
Code Reason 


8 Name not found for locate function, 
or existing structure inconsistent with 
request for non-locate function. 


20 Syntax error in data set name. 
28 Permanent I/O error. 
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IGGOCLC2: Locate 


IGGOCLC2 is the entry point. Control comes 
from: 


e IGGOCLC1 after resolving an alias or 
constructing and entry for BLDA or LNKX 
request. 


e [GGOCLCO otherwise. 


Registers 


4 Base register for this module 
6 Base register for WORKAREA DSECT 
8 Base register for CAMLSTD DSECT 
12 Linkage register for BALR instructions 
13. Base register for BLDLAREA 
14 Linkage register for BALR instructions 


Functions 


This module completes the locate functions, 
or finds the last valid index level for a 
non-locate function. BLDL is used to search 
index levels successively. At each index level, 
one component of the data set name is used. 
When locate-by-name is requested, BLDL is 
used with each component of the data set 
name as the search parameter. When BLDL 
returns an index pointer entry (IPE), use it to 
determine the track address for the next 
search. The search by BLDL continues with 
the next component of the name. 


When BLDL returns a data set pointer entry 
(DSPE) or volume control block pointer entry 
(VCBPE), the corresponding volume list is 
returned to the caller. 


When the request is for a non-locate function 
and BLDL fails to find the next level, the 
update process is initiated. 


The last valid level of the existing index 
structure is saved to use while updating. 


IGGOCLC2 contains skeletal channel programs 
that are used by the non-locate modules. 
These CCW chains are moved to BLDLAREA. 
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Exits 


When the request is a locate function, control 
returns to: 


Initialize and 


Poquaee 
error check for UCATDX 
UCATDX function 


e [GC0002F along with the volume list for the 
data set name (via XCTL SVC instruction). 


e IGGOCLC1 for relative GDG number. 


Relocate CCWs 
into WORKAREA 


When the request is for a non-locate function, 
control passes to: 


e IGGOCLC7 for an error condition. 


e IGGOCLC3 otherwise. 
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Error Conditions 


Code Reason 


8 Name not found for locate request or ee 
existing structure inconsistent with ( “KCTL t9 ) 
GGOCLC 3 

non-locate request. 
12 Last entry found was an IPE, CVPE, 

or alias with locate request. 

. 7 ape UCATDX 
16 Non-existent index levels specified. fot eae 
block in 
. workarea 
20 Syntax error in data set name. 
Do not delete lst or 2nd level block, 
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NOTDEL 
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IGGOCLC3: Update Initialization and Entry Building 


IGGOCLC3 is the entry point. Control comes 
from: 


e IGGOCLC4 after constructing a DSPE for a 
CATBX request. 

e IGGOCLCS after writing a volume control 
block and constructing a VCBPE for a 
CATBX function. 

e IGGOCLC2 otherwise. 


Registers 


4 Base register for this module 

6 Base register for WORKAREA DSECT 

8 Base register for CAMLSTD DSECT 
12 Linkage register for BAL instructions 
14 ‘Linkage register for BAL instructions 


Functions 


When entry is from IGGOCLC4 or IGGOCLCS, 
index levels for a CATBX request must be 
built. Control goes to label CATBX on the 
next subchart. 


When control comes from IGGOCLC2, the 
index control entry (ICE), if not already 
present, and volume index control entry 
(VICE) are read. The request is checked 
against available space in SYSCTLG to ensure 
that there is enough space to make the 
required changes. 


This module constructs new index levels for a 
BLDX function and constructs an index 
pointer entry for the new level to be added to 
the existing structure. When the requested 
function is DRPX or DLTA, the entry to be 
removed is named and IGGOCLC6 will delete 
it. 

When CATBX is requested, IGGOCLC4 is called 
to construct the DSPE. Control returns to 
IGGOCLC3, where the required index levels are 
built and written into SYSCTLG. Each level 
results in an index pointer entry (IPE) that 
must be added to the next higher level. When 
an existing level is reached, control passes to 
IGGOCLC6. 


IGGOCLC3 routes the update request to the 
modules that perform the appropriate 
function. 


Internal Subroutines 


MOVELVL gets the component of the data set 
name for the current index level from the 
name table. 


WRTSRCH writes a new block to SYSCTLG 
and searches for another available block. 
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KEYICE constructs a new index block, with its 
ICE and key. 


TOABSL converts a relative track address to 
an absolute track address. 


TORLTV converts an absolute track address to 
a relative track address. 


10 performs EXCP input/output. This 
subroutine invokes I1GC0002H if a new extent 
of SYSCTLG is required. 


Exits 


Control passes via an XCTL macro instruction 
to: 


e IGGOCLC4 when the requested function is 
CATBX, CAT, RECAT, or UNCAT. 


e IGGOCLCS5 when blocks of SYSCTLG need 
to be freed, or when new blocks have been 
written, but the requested process has been 
aborted. 


e IGGOCLC7 for error conditions. 
e IGGOCLC6 otherwise. 


Control passes via an SVC 28 to IGC0002H 
when a new extent of SYSCTLG is required or 
when SYSCTLG must be re-opened, and 
returns to this module. 


Error Conditions 


Code Reason 


8 Existing structure is inconsistent with 
the requested function. 

12 Attempt to delete a non-empty index 
level. 

20 Not enough space available in 
SYSCTLG to perform the requested 
function. 

28 Permanent I/O error. 
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IGGOCLC4: Entry Building 


IGGOCLC4 is the entry point. Control comes 
from IGGOCLC3 when the requested function 
is CAT, CATBX, RECAT, or UNCAT. 


Registers 


4 Base register for this module 

6 Base register for WORKAREA DSECT 

8 Base register for CAMLSTD DSECT 
12 Linkage register for BAL instructions 
14 Linkage register for BAL instructions 


Functions 


If the requested function is RECAT or UNCAT, 
control passes to label ALTERTN. If the 
request is for CAT or CATBX, control passes 
to label CATRTN. 


This module constructs a new DSPE or 

VCBPE. When there are more than five 
volumes in the volume list, IGGOCLCS is 
invoked to write volume control blocks. 


If the data set name is not for a generation 
data group, control passes to label 
CULMINAT. Part two of the flowchart deals 
with cataloging functions to a generation 
index. The new member of a GDG is checked 
against existing members to see if this is a 
new version of an existing member. 


If the maximum number of entries that a 
generation index can hold is exceeded with 
this addition, the options for GDG are 
processed. 


If EMPTY was specified, IGGOCLCS will 
remove all entries from the generation index 
before adding the new entry. Otherwise, 
IGGOCLCS will remove only the oldest entry 
before adding the new entry. This module 
(IGGOCLC4) flags what is to be done. 


If DELETE was specified, then this module 
(IGGOCLC4) issues the SCRATCH macro 
instruction on every data set name that will 
be removed by IGGOCLCS. If DELETE was 
not specified, nothing is scratched. 


The RECAT and UNCAT functions are 
processed by naming the old entry. IGGOCLC6 
will delete the old entry when it gets control. 
For RECAT, a new entry is also constructed. 
IGGOCLCé6 will add this new entry to the 
catalog. 


Internal Subroutines 


TOABSL converts an absolute track address to 
a relative track address. 
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IO performs EXCP input/output operations. 


GET reads a block from SYSCTLG into the 
input buffer of BLDLAREA. 


SETUP points to the first and last entry in an 
index block. 


INCR bumps the pointer to the next entry in 
an index block. 


BLDENTRY constructs a data set pointer entry 
(DSPE) or a volume control block pointer 
entry (VCBPE). 


SCRATCH performs a SCRATCH macro 
instruction for one data set and its VCBs. 


Exits 


Control is passed via an XCTL macro 
instruction to: 


e IGGOCLC3 when CATBX is being 
performed. 

e IGGOCLC5 when auxiliary reading or 
writing is required: 


— Volume control blocks (VCBs) need to 
be written. 

— VCBs or index blocks need to be freed. 

— The DELETE option of a GDG needs to 
be performed. 

— Updated GDG index blocks need to be 
rewritten. 


e IGGOCLC7 for error conditions. 
e IGGOCLC6 otherwise. 
Error Conditions 


Code Reason 


8 Existing structure is inconsistent with 
requested function. 
16 Non-existent index level required. 
24 Improperly named GDG data set, or 


GDG data set to be added is older 
than existing GDG data sets. 


28 Permanent 1/O error. 
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IGGOCLCS5: First Load of Update 


IGGOCLCS is the entry point. Control comes Control is passed 
from IGGOCLC3 or IGGOCLC4 when blocks of cota aes PRVCBRTN 


7 From LGG0CLC 3 ne 
the catalog need to be written or freed. aia BeEnt to VCB 


Free a chain 
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If a CATBX function is requested and the 
volume list contins more than five volumes, 
volume control blocks are constructed from 
that list and written to SYSCTLG. 
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Internal Subroutines 


WRBLKRTN, WRLSTRTN, EMPTYRTN, 
FRNDXRTN, FRVCBRTN, FRBLKRTN, and 
BLVCBRTN are shown on the flowchart. 


SETUP points to the first and last entry in an 
index block. 


INCR increments the pointer to the next entry 
in an index block. 


TOABSL converts a relative track address to 
an absolute track address. 


TORLTV converts an absolute track address to 
a relative track address. 


10 performs EXCP input/output operations. 
This subroutine invokes IGC0002H if a new 
extent is required. 

Exits 


Control passes via an XCTL macro instruction 
to: 


« IGGOCLC3 when the requested function is 
CATBX. 


« IGGOCLC7 for error conditions. 
« IGGOCLC6 otherwise. 


Control passes via an SVC 28 to IGC0002H 
when a new extent of SYSCTLG is required, 
and returns to this module. 


Error Conditions 


Code Reason 


20 Not enough space available in 
SYSCTLG to perform the requested 
function. 

28 Permanent I/O error. 
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IGGOCLC6: Second Load of Update 


IGGOCLC6 is the entry point. Control comes 
from: 


e IGGOCLC4 when the requested function is 
CAT, UNCAT, RECAT, or CATBX. 


e I[GGOCLC3 or IGGOCLCS. 


Registers 


4 Base register for this module 

6 Base register for WORKAREA DSECT 

8 Base register for CAMLSTD DSECT 
12 Linkage register for BAL instructions 
14 Linkage register for BAL instructions 


Functions 


This module adds or deletes an entry to or 
from a given index block, as set up by earlier 
phases, and ripples the change through the 
index chain as needed. Each entry is taken 
from the buffer INPUT and placed into the 
buffer OUTPUT until the collating sequence of 
the entry is equal to or greater than the name 
in the update request. If the request name is 
equal, that entry is skipped (delete function). 
If the request name is greater, the new entry 
is merged into OUTPUT (add function). 
Overflow entries become an add request for 
the next block in the chain. 


Subroutines named GET and PUT are used for 
input/output. GET reads a block into INPUT, 
a field of WORKAREA, and initializes PUT. 
Entries are transferred from INPUT to 
OUTPUT, another field of WORKAREA. When 
all entries have been exhausted from INPUT, 
another block of the index is read from 
SYSCTLG. 


When OUTPUT is full, a block is written to 
SYSCTLG from OUTPUT by the routine PUT. 
PUT checks all possibilities before writing the 
block and chooses the record of SYSCTLG 
that is most likely to result in contiguous 
blocks of one index. PUT tries to free any 
unneeded blocks; any unneeded block that 
PUT cannot free is later freed by GET. 
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Internal Subroutines 


GET reads one block from an index in 
SYSCTLG. 


PUT prepares and writes one block into an 
index in SYSCTLG. 


TOABSL converts a relative track address to 
an absolute track address. 


TORLTV converts an absolute track address to 
a relative track address. 


IO performs EXCP !/O operations. 


Exits 

Control is always passed to IGGOCLC7 via an 
XCTL macro instruction. 

Error Conditions 


The only exception code from this module is 
28, which indicates that a permanent 
input/output error has occurred. 
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IGGOCLC7: Third Load of Update and Error Handling 


IGGOCLC7 is the entry point. Control Cont¢ol 1s, passed 
normally comes from IGGOCLC6, but can ae . ‘ 
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If an error is discovered, pertinent 
information is gathered into an environment 
record and written to SYSCTLG. The 
exceptional return code is set and all 
resources are freed. Control returns to the 
caller of catalog management via an EXIT SVC 
instruction. 
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Extend ctlg w/ 
ene ae 
ey=O0, u ate 
VICE (rtn Lo) 


54 OS/VS Catalog Management Logic 


Internal Subroutines 
READ reads one block from SYSCTLG. 
WRITE writes one block to SYSCTLG. 


TOABSL converts a relative track address to 
an absolute track address. 


TORLTV converts a relative track address to 
an absolute track address. 


10 performs EXCP input/output operations. 
This subroutine invokes 1GC0002H if a new 
extent of SYSCTLG is required. 


Error Conditions 


This module returns any exception code from 


another catalog management module to the 
caller. This exception code is passed to 
[GGOCLC7 in WORKAREA. 


The only exception code from this module is 
28, which indicates that a permanent I/O 
error has occurred. 


Exits 


IGC0002H may be invoked via an SVC 28 when 
a new extent of SYSCTLG is required. Control 


returns to this module when one has been 
located. 


Control returns to IGC0002F via an XCTL SVC 


instruction. 
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IGCO0002H: SYSCTLG Open/Extend 


IGC0002H is the entry point. Control comes 
via an SVC 28 from: 


e IGGOCLCO or IGGOCLC3 to open a CVOL. 


e IGGOCLC3, IGGOCLCS, or IGGOCLC7 to 
extend SYSCTLG. 


Control also comes via an XCTL macro 
instruction from IGG0553E after extending 
SYSCTLG. 


Registers 
On Entry for Opening: 


0 Zero 
1 Address of UCB table for CVOL 
15 Address of area in which to build 
DCB/DEB chain 


On Entry for Extending: 
0 Address of DCB for SYSCTLG 


On Entry after Extending: 

Q Negative number 

4 Address of EXTEND work area 

9 Address of DCB for SYSCTLG 
10 TTR for new extent of SYSCTLG 
11 Address of UCB 


On Exit: 
1. Address of DCB/DEB chain 


Functions 


When this module is entered to open a CVOL, 
a data control block (DCB) and a data extent 
block (DEB) are built in the work area 
provided by IGGOCLCO. If the catalog is new, 
IGGOCLF2 is invoked to format it. 


Note: The DCB/DEB constructed by this 
module is a modification of that described in 
OS/VS!I System Data Areas and in OS/VS2 
System Data Areas. See Figure 12. 


When this module is entered to allocate 
another extent of SYSCTLG, a test is made to 
see if another extent already exists. If so, 
WORKAREA is modified accordingly, and 
control returns to the caller. 


When another extent does not exist, the main 
storage for the previous DCB/DEB is released 
and a new area is obtained with GETMAIN. 
IGG0553A is invoked to allocate a new extent, 
and a new DCB/DEB is built intu the new 
area (the DCB/DEB is reopened). 


The DCB/DEB built by this module differs 
from that described in OS/VSi System Data 
Areas and d in OS/VS2 System Data Areas. 
These two blocks are merged together; that 
is, they overlap in the same area of main 
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Figure 12. DCB/DEB Built by IGC0002H 
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storage, as shown in Figure 12. Main storage 
for the DCB/DEB is set to zeros before 
building; then only the fields that are shown 
are filled in. The first 20 bytes of the DCB do 
not exist (shown by the dotted line), so the 
area Starts with offset 20 of the DCB. The 
DEB overlays the DCB at offset 40. The fields 
that are named are described in OS/VSi 
System Data Areas and in OS/VS2 System 
Data Areas. 


Internal Subroutines 


GETMAIN gets main storage for the DCB/DEB. 


IO performs EXCP input/output operations. 


Exits 


Control returns to the caller via an EXIT SVC 
instruction when IGC0002H completes its 
function. 


Control returns to the caller via an EXIT SVC 
instruction for an error condition. 


Control passes via an XCTL macro instruction 
to: 


e IGG0553A when another extent is required. 
Control returns via an XCTL macro 
instruction to the entry point, IGC0002H 
(block Al of part A). 


e IGGOCLF2 when the catalog or new extent 
needs to be formatted. Control returns 
directly to the caller. 


Error Conditions 


Code Reason 


4 No extents are allocated. 

8 No more extents are available. 
12 Permanent I/O error. 
72 DOS-to-OS conversion was 


unsuccessful (returned by IGG0533A). 


IGG0553A through IGG0553E are invoked by 
this module and can also return exception 
codes. For details about these modules, refer 
to the publication listed below. 
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IGGOCLF2: SYSCTLG and BPAM Directory Formatter 


IGGOCLF2 is the entry point. Control comes 
from IGC0002H. 


Registers 


Q Number of blocks to be written into a 
BPAM directory (zero when formatting 
SYSCTLG) 


1 Address of DCB for this data set 


2 Number of blocks per track for this 
device 


3 Number of bytes in work area passed to 
IGGOCLF2 


4 Address of work area 


5 Data management count decrement 
value 


6 Starting relative track address (TTR) 
when formatting SYSCTLG 


Functions 


The data set is formatted into 256-byte 
blocks with 8-byte keys. When formatting a 
BPAM directory, the module writes one block 
at a time. When formatting SYSCTLG, the 
module writes several blocks each time. 


If the extent is being formatted during an 
open CVOL request, then this is the first 
extent of SYSCTLG. The first block is 
initialized by writing a volume index control 
entry (VICE) into it. 


If formatting is not being done during an 
open request, then this is an extent of an 
already existing SYSCTLG. The VICE is read, 
updated, and rewritten to reflect the new 
extent. 


The work area that is passed to IGGOCLF2 is 
freed before exit. 
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Control 1s passed 
via XCTL 
IGGOCLF2 
Entered from 
IGCO00 2H 


B1 
Build ECB and 
LOB, relocate 
them 


This loop formats 
SYSCTLG records 


D1 
Init to start 
at beginning of 
dir. and BT Low 
for EQ 


End of 
extend been 
reached 


write full 


k of 


is loop formats 
AM Directory records 


F2 
Set up Ist CCW 
to write 
special blk for 
empty directory 


2 


Set up channel 
program to 
write EOD mark 


Last recor 
been written 


BPNLST 


Write specified = 
records (rtn 
IQ) 


All records 
been “written 


Internal Subroutines 


CNVT converts a relative track address to an 
absolute track address. 


10 performs EXCP input/output operations. 
RELOC builds channel programs for 
input/output. 

Error Conditions 


IGGOCLF2 returns one exception code, 12, 
which indicates that an I/O error has 
occurred. The caller of catalog management 
never sees this code. 


Exits 


Control is passed to the caller of 1GC0002H 
via an EXIT SVC instruction. 


References 

Page 
Item number 
1GC0002H 56 
VICE 66 
WORKAREA 68 


01D2 


to pass last TT 


in catalog to 


Request 
to format 
extent of 


catalog (rtn IQ) 


EXTNDA 


e 


Update 
information in 
WORKAREA for 
catalog extents 


Read the 
SYSCTLG DSCB 
(rtn 10) 


D1 


D2 


Set formatted 


Set up next TT switch in DSCB 


El 


Update VICE in 
data set 


Dae 


EXTENDED ; 


FREEMAIN 


rovided b 
PIECOOO2H * 


Exlt 1S to caller 
of IGCOOO2H 


Feed Ol 
eo via SVC ) 
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Microfiche Directory 


This chapter helps you relate the discussions in this book to the assembly listings J 
found on microfiche. The rightmost columns of this directory contain page 

number references to Method of Operation figures and/or flowcharts where more 
information can be found. The microfiche are found under the component name 

“Data Management.” 


Module/ 


Entry Point /|Microfiche Method of Flowchart 
Name Name Description Operation Page Page 


1IGG0002F 1GG0002F Controller I to route catalog 
requests 
1GG0002F 1GG0002F Controller II to route catalog 
requests 
IGGOCLCA |IGGOCLCA [Controller II to resume eh 
processing of OS/VS requests 
> 


IGGOCLCB |IGGOCLCB Controller II to resume 
processing of VSAM requests 


IGGOCLCO |IGGOCLCO [Initialization for catalog pO 
management routines 


— = 
processing 
20 
building 
IGGOCLC4 
IGGOCLCS 
IGGOCLC6 


IGGOCLC6 Second load of apdate 22, 23 
IGGOCLC7 |IGGOCLC7 [Third load of update, exit ; 
processing, and error handling 
1GC0002H _|SYSCTLG open or extend 


IGGOCLF2 IGGOCLF2 SYSCTLG and BPAM 0 58 
directory formatter 
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Data Areas 


The data areas and record formats in this chapter are described in four columns, 
which are interpreted as follows: 


Offset 
The numeric address of the field relative to the beginning of the area. The 
first number is the offset in decimal, followed (in parentheses) by the 
hexadecimal equivalent. 


Bytes and Alignment 
The size (number of bytes) of the field and its alignment relative to the fullword 
boundary. 


Examples: 


4 A 4-byte field beginning on a word boundary. 
.3 A 3-byte field beginning on a halfword boundary and running into the 
next word. 
ne A 2-byte field beginning at the low-order byte of a word and running 
into the next word. 


Name and Content 
A name that identifies the field. This name appears as a label in the assembly 
listings for the catalog management routines. 


This column is also used to show the contents of the field or the bit settings of 
flag fields (the state of bits in a byte). When the column is used to show the 
state of the bits (0 or 1) in a flag byte, it is shown as follows: 


satiate The 8 bit positions (0-7) in a byte. For ease of scanning, the 
high-order (leftmost) 4 bits are separated from the low-order 4 bits. 


> ne A reference to bit 0. 
| een Bit O is on. 
0... .... Bit O is off. 


a xx A reference to bits 6 and 7. 


Bit settings that are significant are shown and described. Bit settings that are 
not presently shown are understood to be reserved bits. 


Field Description and Meaning 
The use of the field. 


SYSCTLG Entry Formats 


This section describes the formats of the entries of SYSCTLG, along with the 
symbolic labels that are used to refer to their fields. The entries are arranged 
alphabetically. 


Except for the volume control block (VCB), SYSCTLG entries have a similar format. 
These entries share a common definition for the first 12 bytes. The shared names 


are: 
ENAME ETTR ETYPE 
(8 bytes) (3 bytes) (1 byte) 


Individually named fields follow either ETTR or ETYPE. 


The entries in a SYSCTLG block begin in the third byte of the block. The first 
halfword of the block contains the binary number of the bytes that are used in this 
block, including the halfword count field. 
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Alias Entry (AE) 


An alias entry defines an alternate name for the high-level qualifier of a data set 


name. 


Control Volume Pointer Entry (CVPE) 


12(C) oo ETRUEN 


Name; contains the alias of the high-level 
index whose relative track address is found at 
offset 8 of this entry. 


Address; contains the relative track address 
(TTR) of the first block of the index named at 
offset 12 of this entry. 


Type; indicates that this is an alias entry; also 
that four halfwords follow in the remainder of 
the entry. 


True name; contains the name of the index 
whose alias appears at the beginning of this 
entry. 


A control volume pointer entry can appear only in volume indexes. Two forms are 
possible: the old form, created prior to Release 17 of IBM System/360 Operating 
System, and the new form, created since that release. Both forms are shown here. 


Old CVOL Pointer Entry 


New CVOL Pointer Entry 
Bytes and 
Alignment 
pe ft 


8(8) 


- a 
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Bytes and Name and 
Alignment /Content Field Description and Meaning 


X‘000000’ 


11(B) ETYPE 
x‘03’ 


12(C) [= 3 EVOLIDO 


Name and 
Content 


EDEVTYP_ /|Control volume device type; contains the 


16(10) [* EVOLID 


Name field; contains a high-level name that 
appears in the volume index of the control 


volume identified at offset 12 of this entry. 
Zero field. 


Type; indicates that this is either an old CVOL 
pointer entry (CVPE), or an index control 
entry (ICE). An ICE always appears as the 
first record of an index level; a CVOL pointer 
entry always appears in the volume index. 
This is also the number of halfwords that 
follow in the remainder of the entry. 


Serial number of the control volume whose 
volume index contains an entry for the name 
found at the beginning of this entry. 


Field Description and Meaning 


Name; contains a high-level name that 
appears in the volume index of the control 
volume identified at offset 12 of this entry. 


Zero field. 


Type; indicates that this is a new CVOL 
pointer entry (CVPE) or the volume index 
control entry (VICE). The VICE always 
appears as the first entry in the first block of 
SYSCTLG; a CVOL pointer never appears as 
the first entry of the first block. Also 
indicates that five halfwords follow in the 
remainder of the entry. 


binary device code of the control volume 
whose volume index contains an entry for the 
name found at the beginning of this entry. 


Serial number of the control volume whose 
volume index contains an entry for the name 
found at the beginning of this entry. 


Data Set Pointer Entry (DSPE) 


A data set pointer entry can appear in any index level. It contains the simple name 
of a data set and from one to five 12-byte fields, each of which identifies a volume 
on which the named data set resides. 


Bytes and =| Name and 
Alignment Content Field Description and Meaning 


Name; contains the simple name of the data 
set whose volumes are identified at offset 12 of 
this entry. 


EDSCBTTR |Address; contains either binary zero or, when 
the data set resides on only one volume, the 
relative track address (TTR) of the data set 
control block (DSCB) for this data set in the 
volume table of contents (VTOC). 


Type; indicates that this is a data set pointer 


entry (DSPE). Also indicates the number of 
halfwords that follow in the remainder of this 
entry. 


EVOLCNT  |Volume count; contains the binary count of 
the number of volumes identified beginning at 
offset 14. 


..12 to 60 EDATA Volume entries; contains from one to five 
12-byte entries, each of which identifies one 
volume on which the data set resides. Catalog 
management neither uses nor checks the 
contents of this field. 


Generation Index Pointer Entry (GIPE) 


A generation index pointer entry can appear in any index except a generation 
index. It corresponds to the simple name used in the relative name for a GDG data 


set. 
Bytes and Name and 
Alignment (Content Field Description and Meaning 


Name; contains the name of the generation 
index to which this entry points. 


Address; contains the relative track address of 
the first block of the generation index named 
in this entry, in the form TTR. 


Type; indicates that this is a generation index 
pointer entry (GIPE). Also indicates that two 
halfwords follow in the remainder of this 
entry. 


Flags; contains the options specified by the 
creator of the generation data group: 


DELETE option. 
/EMPTY option. 


Maximum count; contains a binary number 
specifying the maximum number of 
generations allowed in the generation index at 
one time. 


Current generation count; contains the binary 
number of generations currently cataloged in 
the index. 
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Index Control Entry (ICE) 


The index control entry is the first entry in all indexes except the volume index. 


Bytes and Name and 
Alignment (Content Field Description and Meaning 
0(0) 8 INAME Name; low value of binary 1 ensures that this 
X‘00...01’ _|is the first entry in the index. 


3 Last block address; contains the relative track 
address of the last block assigned to the index, 
in the form TTR. 

11(B) ITYPE Type; indicates that this is either an ICE or an 

x*‘03’ old CVOL pointer. An ICE always appears as 
the first entry of an index; an old CVOL 

12(C) 3 IFSTBLK 
address of the block in which this entry 
appears, in the form TTR. 

15(F) ILIASCNT |Number of aliases; contains a binary count of 
aliases assigned to the index. This count is 
always zero for indexes that are not high-level. 
An index cannot be deleted if this count is 
non-zero. 


pointer always appears in the volume index. 
wo) | Reserved 


Also indicates the number of halfwords that 
follow in the remainder of the entry. 


First block address; contains the relative 


Index Link Entry (ILE) 


An index link entry is always the last entry in any index block. It is used to link 
blocks of one index into a chain. 


Bytes and Name and 
Alignment (Content Field Description and Meaning 


Name; high value (all bits on) ensures that this 
is the last entry in the index. 


Link address; contains the relative track 
address of the next block of the same index, if 
there is one, in the form TTR. When this is 
the last (or only) block, this field contains 
binary zero. 


Type; indicates that this ts either an ILE or an 
IPE. The name field of an ILE always 
contains X‘FFFFFFFFFFFFFFFF ; the name 
field of an IPE never does. Also indicates that 
there are no more halfwords in the entry. 


Index Pointer Entry (IPE) 


The index pointer entry can appear in any index except a generation index. It 
points to a lower index. 


Bytes and Name and 
Alignment (Content Field Description and Meaning 
0(0) re | ENAME Name; contains the name of the index to 
which this entry points. 


8(8) ETTR Index address; contains the relative track 


address of the first block of the index named 
11(B) - ETYPE 
x‘00’ 


in this entry, in the form TTR. 
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Type; indicates that this is either an IPE or an 
ILE. The name field of an ILE always 
contains X‘FFFFFFFFFFFFFFFF’; the name 
field of an IPE never does. Also indicates that 
there are no more bytes in the entry. 


Volume Control Block (VCB) 


A volume list can be.recorded in one or more volume control blocks. Each volume 
control block is one block of the SYSCTLG data set, and can identify up to 20 
volumes on which one data set is recorded. 


Note: This block is different from other blocks of SYSCTLG. The first halfword 
C does not contain the number of bytes used in the block as do other SYSCTLG 
blocks. The field VCBVOLCT, shown below, is the first halfword of the VCB block. 


Bytes and Name and 
Alignment (Content Field Description and Meaning 


0(0) 2 VCBVOLCT |Number of volumes; contains the number of 
volumes identified in this and subsequent 
volume control blocks. This number its 
reduced by 20 for each subsequent volume 
control block. For example, if a data set 
resides on 61 volumes, it uses four volume 
control blocks. This field of each block 
contains 61, 41, 21, and |, respectively. 

2(2) ..12 to 240 VCBVOLS_|Volume identifications; contains from 1 to 20 
12-byte entries, each of which identifies one of 
the volumes on which the data set resides. 
Catalog management neither uses nor inspects 
the content of these entries. Each 12-byte 
entry contains a 4-byte device code, a 6-byte 
volume serial number, and a 2-byte data set 
sequence number. 


242(F2) Zero field. 


242(FC) 3 Chain address, contains the relative track 
address of the next volume control block, if 
there is one, in the form TTR. If this is the 

last (or only) block of the volume control 

block, this field contains binary zero. 
Psst X00" Zero field 


( Volume Control Block Pointer Entry (VCBPE) 


A volume control block pointer entry can appear in any index. It is used when a 
data set resides on more than five volumes. 


Bytes and Name and 
Alignment /|Content Field Description and Meaning 


0(0) ENAME _ |Name; contains the simple name of the data 
set whose volumes are identified in the volume 
control block that is pointed to by this entry. 


Address; contains the relative track address of 
the volume control block identifying the 

volumes containing the data set named in this 
entry, in the form TTR. 


Type; indicates that this is a volume control 
block pointer entry. Also indicates that one 
halfword follows in the remainder of this 
entry. 


120) Zero field, 
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Volume Index Control Entry (VICE) 


The volume index control entry is always the first entry in the first block of data 
set SYSCTLG. 


It is the control record for the entire data set, and acts as an ICE for the volume 
index. 


Bytes and Name and 
Offset Alignment §Content Field Description and Meaning 


Name; always contains a binary one to 
ensure that this ts the first entry of the 
volume index. 


VLSTBLK _ |Last block address; contains the relative track 
address of the last block of the volume index, 
in the form TTR. 


VTYPE Type; indicates that this is the volume index 
x‘05’ control entry or a new CVOL pointer entry. 
The volume index control entry is always the 
first entry of the first block of SYSCTLG; a 
CVOL pointer is never the first entry. Also 
indicates that five halfwords follow in the 

remainder of the entry. 


VCLSTBLK |Last block of the catalog; contains the 
relative track address of the last block in 
_ SYSCTLG, in the form TTR. 


VHIREC Contains the number of TTRs in 
VCLSTBLK. Note that this field is the last 
byte of VCLSTBLK (offset 12). 


15(F) _ Zero field. 


16(10) VFHOLE ||First available block; contains the relative 
track address of the first unused block in 
SYSCTLG, in the form TTR. 


19(13) sak x‘00’ Zero field. 


20(14) Reserved. 


Environment Record (EREC DSECT) 


The environment record is written by module IGGOCLC7 under certain error 
conditions. This record is useful in diagnosing problems using the catalog 
management routines. Reading the environment record is described in the 
chapter, “Diagnostic Aids.” 


Bytes and |Name and 
Alignment Content Field Description and Meaning 


Reserved. 


8(8) ERTIME _ |Time stamp, as produced by the TIME macro 
instruction. 


16(10) ERCAMLST First four bytes of the callers parameter list 
produced by the CAMLST macro instruction 
(see description of CAMLSTD on page 67). 


20(14) 1 ERMODMAP |Field MODMAP!1 from WORKAREA, 
described on page 72. 


21(15) 1 ERFLAGI /|Field FLAGI from WORKAREA, described 
on page 70. 

ERFLAG?2 = |Field FLAG2 from WORKAREA, described 
on page 71. 


sal 
23(17) ol ERFLAG3 _ |Field FLAG3 from WORKAREA, described 
on page 70. 
24(18) ERERRCOD |Fields ERRCATSV and ERRLOCSV from 
WORKAREA, described on page 55. 
26(1A) 2 ERNAMTTR |Level name, TTR, type, and volcnt; the first 
14 bytes of a general entry. 


40(28) ERREGSV_ |Contents of general registers 0 through 14 at 
the time the environment record is written 
(register 15 is destroyed by module 
IGGOCLC7). 


100(64) Contents of WORKAREA from offset 12 
bytes (label TTR) through offset 39 bytes. 


22(16) 


66 OS/VS Catalog Management Logic (cont.) 


(cont. ) 


Bytes and Name and 
Alignment {Content Field Description and Meaning 


128(80) 18 ERINPUT [First entry in INPUT, a field described on 
page 72. 


146(92) - EROUTPUT |First entry in OUTPUT, a field described on 


page 72. 


164(A4) EROPTNCC | Field OPTNCCW from WORKAREA, 
described on page 72. 


176(B4) ERIOB Field IOB from WORKAREA, described on 
| page 72. 


212(D4) ERNAME _s|Fully qualified name provided by the caller. 


CAMLSTD DSECT 


CAMLSTD describes the parameter list provided by the caller of catalog 
management. It maps the result of the CAMLST macro instruction. 


| Bytes and | Name and 
Offset Alignment _—_Content Field Description and Meaning 


0(0) I CAMOPTNI |First option byte. 

Catalog is not on SYSRES. 
CAT or CATBX request. 
RECAT request. 

'UNCAT or UNCATDX request. 
| Locate-by-block request. 


Second option byte. 

BLDX or CATBX request. 
BLDG request. 

BLDA request. 

LNKX request. 

DLTX or UCATDX request. 
DSCB TTR has been specified. 
DLTA request. 

Third option byte. 

DRPX request. 

Scratch GDG data sets. 


Empty generation index when maximum 
generation count is reached. 


Search VS catalog first. 
Search only one catalog. 
VS CAMLST 

VSAM parameter list. 


CAMGEN _|Maximum generation count. 


| CAMPTRI_ {Address of the name field in caller's area. 
For locate-by-block, the name field contains a | 
relative track address instead of a name. 


4 CAMCVOLP |Address of CVOL volume serial number (a 
6-byte field). 


CAMPTR3_ |Address of caller's third parameter. Meaning 
depends on the function: 


Locate Callers 265-byte work 
area 

BLDA 8-byte name field 
LNKX 10-byte volume 
identification 

CAT, CATBX 

or RECAT Volume list 

Other Not used 


16(10) CAMDSCBP |Address of three-byte field containing the 
relative track address (TTR) for the Format | 
DSCB for the data set named through 
CAMPTRi. 
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RPSD DSECT 


WORKAREA DSECT 


RPSD describes the CCW chain used for rotational positioning sensing (RPS) 
support. 


Bytes and Name and 
Offset Alignment Content Field Description and Meaning 
0(0) I ie, RPSCCW __|Two double-words: RPSSS and RPSTIC. 


0(0) RPSSS Set sector CCW. 


8(8) a ae RPSTIC TICs to normal channel program. 

16(10) ie RPSINPUT |Four words: RPSCNVT, RPSDDKR, RPSR1, 
and RPSPTR. 

16(10) RPSCNVT [Address of supervisor routine to convert sector 
value. 

20(14) RPSDDKR [Block size (DD, 256 bytes), key length (K, 8 
bytes), and record number. 

24(18) RPSRI Address of location of this DSECT during use. 

28(1C) 4 RPSPTR  |Type and address: the first byte contains the 
device type code, and the last three bytes 
contain the sector value. 

32(20) RPSAVE 10-word register save area. 


WORKAREA serves all catalog modules. WORKAREA Serves as intermediate 
storage, Communications area, and buffers. BLDLAREA is a portion of WORKAREA 
that serves the resident BLDL routines. For a locate function, BLDLAREA is 
separate from WORKAREA. 


Many of the fields in the area overlay other fields, and sections of an area can have 
more than one label. Figure 13 shows where these overlays occur, by label. The 
listing for any module shows more labels and more detail; only the most significant 
are shown here. 


When function is non-locate, one area (GETMAIN) 
‘ig used for all purposes. 


_ When function is locate, two areas are used. Space 
for BLDL comes from GETMAIN. 


WORKAREA 


WORKAREA 
The caller’s area is used for WORKAREA 


RETDATA 
The caller's area is redefined as RETDATA 
fo pass data back to the caller. 


BLDLAREA 


{Imput) - 
. BLDLAREA 


(Output) 


Figure 13. Data Area Hierarchy 
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Bytes and Name and 
Alignment (Content Field Description and Meaning 
0(0) BLDLIST  |List parameter for BLDL or, when 
SAVETTR3 |appropriate, the name of the last valid index 
level. 


4(4) 8 NAME Name in the entry that is being operated on, 
ALIASNAM or the alias. 
5(5) 4 GENNO __|Generation number portion of an absolute 
GDG name. 
12(C) 3 TTR Relative track address in the current entry, in 
the form TTR. 


15(F) Seal TYPE Type of entry; also the binary number of 
halfwords following in the remainder of the 
entry. TYPE is interpreted as: 

X*00’ either an index pointer entry (IPE) or an index 
link entry (ILE). The name field of an ILE 
always contains X‘FFFFFFFFFFFFFFFF ; the 
name field of an IPE never does. 

xX‘Ol’ Volume control block pointer entry (VCBPE). 

X‘02’ Generation index pointer entry (GIPE). 

x‘03’ Index control entry (ICE) or old CVOL 
pointer entry (CVPE). An ICE always appears 
as the first entry of the index; a CVPE always 
appears in the volume index. 

X‘'04 Alias entry (AE). 

x‘05’ Volume index control entry (VICE) or new 
CVOL pointer entry (CVPE). The VICE 
always appears as the first entry of the first 
block of the catalog; a CVPE always appears 

later in the volume index. 

X‘07’ Data set pointer entry (DSPE with one volume 
identification). 

X‘O0D’ DSPE with two volumes. 

x‘13? DSPE with three volumes. 

x*19° DSPE with four volumes. 

X‘1F’ DSPE with five volumes. 


16(10) — TRUE The true name to which the alias in offset 4 
relates. 


16(10) VOLCNT  |Number of volumes identified in DATA when 
the current entry is a data set pointer entry 
(DSPE). 


16(10) DATA Volume identifications for DSPE. 


88(58) ERRCATSV /|Error code generated for non-locate function. 
89(59) ERRLOCSV |Error code generated for locate function. 


90(5A) Switches declaring requested function. 

Py Pence The index control entry (ICE) must be read. 

el ree SYSCTLG has no more room during CATBX 
or BLDX function. 

cdr easscad The DCB/DEB was freed by SVC 28 
processing. 

ee eee CATBX request. 

a elad UCATDX request. 

Piensa | Locate request. 
RECAT request. 


(cont.) 
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70 


(cont.) 


Byt 
Align 


91(5B) 


92(S5C) 


120(78) 8 


128(80) 


es and 
ment 
| 


NEXTKEY 
NEXTCNT 


ICE 


136(88) 


148(94) 


Name and 
Content Field Description and Meaning 


Switches used to specify flow of control. 
RPS device. 
‘( has been found in the data set name. 


Last entry found was a CVOL pointer entry 
(CVPE). 


Generation index pointer entry (GIPE) has 
been found. 


Save area for temporarily storing the contents 
of general purpose registers. 


The key or count of the next block beyond the 
one read. 


Index control entry; see the description on 
page 64 for individual fields. Only bytes 8 


through 15 are saved here. 
VICE Volume index control entry; see the 
description on page 66 for individual fields. 


_|Only bytes 11 through 18 are saved here. 


Switches to invoke functions of [GGOCLCS. 
Absolute GDG name found. 

Free index blocks. 

Read a block for updating. 


Process EMPTY option of generation data 
group (GDG). 


Write the last block of a GDG chain when the 
GDG is full and a new one is being added. 


Build volume control blocks (VCBs). 
Free VCBs. 
Write a block. 


149(95) 
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FLAG4 


ie 


NAMLEN 


1. 


Switches to specify the flow of control in 
IGGOCLC6. 


New entry has been inserted into block now in 
the work area. Updating is in process. 


The updated block has been written into 
SYSCTLG. Updating is complete. 


The block following the block pointed to by 
field WRITETTR is free. 


The first write has occurred. 


The block following the block pointed to by 
field LINKTTR is free. 


Length of the full name given by caller minus 


NAMDELMP 
NAMLSTP 


Address of last delimiter in given name. 


'Pointer to last displacement of given name in 
ithe name table. 


FLAGS 


Switches to specify flow of control in 
IGGOCLC7. 


Low-level index is involved. 

VFHOLE needs to be updated. 
LSTBLK needs to be updated. 
FSTBLK needs to be updated. 


(cont.) 


(cont.) 


Bytes and = |Name and 
Alignment (Content Field Description and Meaning 


162(A2) MODMAPI 


Trace of modules that have been entered. The 
appropriate bit is set to | as each module ts 
entered. There is no bit for module IGCO0Q02F 
or IGGOCLCO, because these modules are 
always entered before any other. 


sitar Sau IGGOCLCI1 
IGGOCLC2 
IGGOCLC3 
IGGOCLC4 
IGGOCLCS5 
IGGOCLC6 
IGGOCLC7 


Address of the entry point of the supervisor 
routine BLDL, IECPBLDL (copied from field 
CVTPBLDL of the CVT). 
BLDLISTP_ |Address of the list to be completed by BLDL 
(address of field BLDLIST, offset 0 of this 
DSECT). 


DCBADDR |Address of the data control block (DCB) for 
the control volume. 


DEBADDR _|Address of the data extend block (DEB) for 
the control volume. 


FOUNDENT | Address of an entry in an input/output buffer. 


EPTORLTV |Address of the entry point IECPRLTV, a 
supervisor routine that converts absolute track 
addresses to relative track addresses (copies 
from field CVTPRLTV of the CVT). 


4 EPTOABSL | Address of the entry point IECPCNVT, a 

supervisor routine that converts relative track 
addresses to absolute track addresses (copied 
from field CVTPCNVT of the CVT). 


SVRBEXTP. |Address of the extension to the SVRB. 


ADDING _ |Address of new entry, meaningful only when 
bitQ of FLAG4is‘1. | 


200(C8) 16 XCTLPARM | Parameters for XCTL SVC. 


216(D8) LNKENTRY |General form in index link entry (ILE). The 


first eight bytes contain 
X‘FFFFFFFFFFFFFFFF . 
224(E0) 7 4 
228(E4) 4 


164(A4) EPBLDL 


168(A8) 


172(AC) 


176(BO) 


184(B8) | 4 


188(BC) 


192(CO) 
196(C4) 


LINKTTR |Last four bytes of LNKENTRY; contains the 


TTR for this ILE. 


Save area for relative address of block to be 
written. 


Relative track address of block that contains 
an index control entry (ICE). 


| 236(EC) 4 SAVETTR __/Save area for any relative track address. 


WRITETTR 


232(E8) 4 ICETTR 


240( FO) READTTR  |Save area for relative address of block to be 
| 
244(F4) Pointer to catalog controller. 
248(F8) 2 Number of levels of the name that were found. 
250(FA) fa Number of levels in given name. 


252(FC) 
256(100) 


Device-type portion of an identification. 


Angular displacement value (theta) for 
rotational positioning support (RPS). 


257(101) INDEXLEN Length of all levels given except the last. Used 
with SCRATCH macro instruction. 


(cont.) 
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(cont.) 


Name and 
Content 


Bytes and 
Alignment 


258(102) ERRSV2H 


259(103) 


16(10) DSNAME 


60(3C) 


SCRPARM 


72(48) SCRVOLS 


Field Description and Meaning 


Exceptional return code from module 
1IGC0002H. 

Serial-number portion of a volume 
identification. 


Data set name to be scratched (when 
processing GDG data sets). 


Parameter list for SCRATCH macro 


instruction. 
Volume list for SCRATCH macro instruction. 


32(20) 


128(80) 8 


NAMTABLE 


136(88) | 8 | PKDNUMBR 
0(0) 
6 


REDSCBT 


259(103) RETCVOL 
265(109) 3 VICESAVE 


BALREGS 
BLDLAREA 


268(10C) 
272(110) 


528(210) 
648(288) 


120 BLDLCNT 


BASESAVE 


- 


536(2 18) 
272(110) 
272(1 10) 


44 
256 
256 


RESALIAS 
INPUT 


528(210) 
536(218) 
544(220) 


TICI 


552(228) 
560(230) 
568(238) 
576(240) 
584(248) 
588(24C) 
630(274) 
638(27C) 
644(284) 


4 


| 


OPTNCCW 


| SKE _|Search-Key-Equal CCW. 
TIC2 Transfer-In-Channel CCW. 


Name table containing the length and 
displacement of each component of the given 
name. 


NAMDELIM |Last delimiter in the given name, either “b’ or 
ie 


Work area for Convert-to-Binary instruction 
used with relative GDG processing. 


Work area for Pack instruction used with 
relative GDG processing. 


RETDATA | Volume list returned to caller. 


Relative track address of the DSCB in the 


VTOC for a single-volume data set, as 
returned to the caller. 


Serial number for the control volume 
containing the returned volume list. 


Save area for volume index control entry 
(VICE) information. 


Save area for register used in BAL instruction. 


Work area for use by BLDL routine; for a 
‘locate function, WORKAREA is in two parts, 
;and BLDLAREA is the second part. 


|Parameters for BLDL routine. 


Save area for the register that would otherwise 
be destroyed by BLDL. 


Work area used when resolving an alias name. 


Input buffer for channel program. 


TRTABLE  |Translate table used with TR instruction to 


SIDE] 


analyze the given name. 
Search-ID-Equal CCW. 
In-Channel CCW. 


CCW that is changed to do the required 
input/output function. 


Read-Count CCW, 


Transfer- 


NOP CCW. 

Event control block for channel programs. 
Input/output block for channel 
Read-Key-Data CCW. 
Read-Data CCW. 


Write-Key-Data CCW. 


programs. 


652(28C) 264 
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RC 
SKE 
NOP 
ECB 
RKD 

WKD 
OUTPUT 


Output buffer for channel programs. 
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Reading Dumps 


Main Storage Dump 


This chapter provides several aids that can be useful when diagnosing difficulties 
with the catalog management modules. These aids tell you: 


e What to look for in a main storage dump. 
¢« How to dump the SYSCTLG data set. 


e« A description of an environment record that is written when an error is 
detected. 


e How to determine what modules are involved in a particular case and what the 
flow of logic is between them. 


Two kinds of dumps can be used while diagnosing trouble with catalog 
management routines: main storage dumps and SYSCTLG data set dumps. This 
section points out significant diagnostic clues to look for. It does not explain the 
full meaning of dumps; for that information, see OS/VSi Debugging Guide, 
GC24-5093, or OS/VS2 Debugging Guide, GC28-0632. 


Main storage dumps are rarely helpful. Unless the error that caused the ABEND 
was actually in one of the catalog management routines, the transient areas (or 
paging areas) will probably have been used by another module of the operating 
system. 


If, however, an ABEND dump was produced because of an error in one of the 
catalog modules, then look at the content of the general registers at the time of the 
ABEND. The most significant registers are: 


Register 4 _ Base register for all catalog management routines. This register 
points to the module that failed. 


Register 6 Pointer to WORKAREA (described on page 68. The field MODMAP1! 
shows which modules have been entered; compare this to the 
expected path for the requested function. The section ‘‘Module 
Selection Charts,” on page 76, shows the path for each function. 


Register 8 Pointer to caller’s CAMLST, described on page 67. Check the 
parameters in CAMLST carefully to be sure that the requests are 
valid. 


Have the following items available before requesting additional assistance: 


¢ Source or input listing for the use of catalog-management routines (be sure 
MSGLEVEL=(1,1)). 


e Main storage dump produced by using a SYSABEND DD statement. 
« Dump of SYSCTLG data set. 
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SYSCTLG Dump 


There are several ways to dump a data set; this discussion assumes that HMASPZAP 


is used. (In VSI, the program is HMASPZAP; in VS2, the program is AMASPZAP.) 
HMASPZAP is a Service-aid program that operates under the operating system. 
HMASPZAP is described in OS/VS; Service Aids, GC28-0633. 


To dump the catalog with HMASPZAP, use the following JCL, where the SYSLIB DD 
card points to the CVOL to be dumped: 


//DUMPSTEP EXEC PGM=HMASPZAP 
//SYSPRINT DD SYSOUT=A 
//SYSLIB DD DSNAME=SYSCTLG, UNIT=xxxx, 
// VOL=SER=xXxXXxXxXxX,DISP=OLD, 
// DCB=( KEYLEN=8 ) 
//SYSIN DD * 
ABSDUMP ALL 
/* 
This JCL is used to dump the entire catalog; you can dump a portion by specifying 
beginning and ending track addresses. 


The DCB parameter KEYLEN in the SYSLIB DD statement formats the key as well 
as the data for each block. The key appears as the first two words of the first line 
of each block. The data for the block begins in the third word. 
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Example of a SYSCTLG Dump 


Figure 14 shows an actual dump of the catalog. Entries in the volume index are 
outlined, and other blocks of the catalog are identified. 


KEY CNT VICE IPE ILE CVPE 
DSPE **CCHHR- 001000601 __RECORD_LEWGTH- 0108 = 
200900 | SEEEEEEE FFFFFFFF | '0074p000_* 00000000 ___|_ 0010000 __01050000__11000000 
00002 C4C5D7E3 40404040 __ 00000007 __ 00013000 __| /2001C4E4 _D4ESDED3 _—0000F9D5_% ESDSE3D6 | Alia 
000040 , D9E80000 00053000 2001FOFO  FOFOFOF1 D7C1E8D9 D6D3D340 00000200 Owe 
000060 © 40404040 00000204  =D7C1E8D9 _D6D3D340 FFFFFFFF = FFFFFFFF 00000000 | 00000000 
000080 | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
0000A0 | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
0000c0 | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
0000E0 | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 _00000000 
000100 | 00000000 00000000 CNT GE 
KEY ~#*CCHHR- 0001000602 RECORD LENGTH 0108 First block of 
0000 D3C9E2E3 40404040 | OOFEPO0O0 00000000 00010000 7 02030000 02010000 J cipscsca- "index ‘PAYROLL 
000020 | C9E5C540 O0000001F 00053000 2001C4E4 D4E5D6D3 00003000 2001C4E4 E5D3F1 
000040 | 00003000 2001C4E4 D4E5D3F2 000030C0 2008E5C3 C2C3D2F1 000030C0 2008E5C3 
000060 | c2c3D2F2 0000D3C1 C2D6D940 40400000 001F0005 30002001 C4E4D4E5 D6D30000 
000080 | 30002001 C4E4D4E5 D3F10000 30002001 C4E4D4E5 D3F20000 30C02008 £5C3C2C3 
0000A0 | D2F10000 30c02008 E5C3C2C3 D2F20000 D3C9E2E3 40404040 0000001F 00053000 
0000CcO | 2001C4E4 D4E5D6D3 00003000 2001C4E4 D4E5D3F1 00003000 2001C4E4 D4ESD3F2 
0000E0 | 000030CO 2008E5C3 C2C3D2F1 000030C0 2008E5C3  C2C3D2F2 OOOOFFFF FFFFFFFF 
000100 | FFFFO090 03000000 


ee i 
KEY CCHHR- 0001000603 


000 FFFFFFFF 
000020 D6D30000 
000040 E5C3C2C3 
000060 00053000 


000080 
OOOGA0 
0000C0 
OOO0EO 
000100 


D4ESD3F2 
D3C1D9E8 
FFFFFFFF 
00000000 
00000000 


KEY **CCHHR- 0001000604 
“OO0000——— FFFFFFFF 


000020 00003000 
000040 C2C3D2F2 
000060 00000000 
000080 00000000 
OOO0A0 00000000 
0000C0 00000000 
QOOOEO 00000000 
000100 00000000 
**#CCHHR- 0001000605 
KEY FFFFPFFF 
000020 OBESFOFO 
000040 00070001 
000060 2001C4E4 
000080 D6D30000 
0000A0 00000000 
0000CO 00000000 
OOOOEO 00000000 
000100 00000000 


**CCHHR- 0001000606 


090000" FFFFFFFF 
KEY ~o00020 [pep30000 


000040 E5C3C2C3 
000060 00053000 
000080 D4E5SD3F2 
0O000A0 FFFFFFFF 
0000C0 00000000 


OOOOEO 
000100 


00000000 
00000000 


**CCHHR- 0001000607 


00000 0000000 
KEY —tosbeo FESO 
000040 | 00000000 
000060 | 00000000 
SAOK AC 900n0Cc 


Figure 14. Example of a SYSCTLG Dump 


RECORD LENGTH- 0108 


FFFFFFFF 
30002001 
D2F 10000 
2001C4E4 
000030C0 
40400000 
00000600 
00000000 
00000000 


OOCOD4D6 
C4E4D4E5 
30C02008 
D4E5D6D3 
2008E5C3 
04010000 
00000000 
00000000 


RECORD LENGT 


FFFFFFFF 
2001C4E4 
000030cC0 
00000000 
00000000 
00000000 
00000000 
00000000 


00000000 | 


RECORD LENGTH- 0108 


FFFFFFFF 
00000007 
30002001 
D4E5D6D3 
FFFFFFFF 


00000000 
00000000 
00000000 
00000000 


RECORD LENGTH- 0108 


FFFFFFFF 
30002001 
D2F 10000 
2001C4E4 
000030C0 
FFFFOOO00 
00000000 
00000000 
00000000 


RECORD LENGTH- 0108 


D4E5D3F2 
2008E5C3 
00000000 
00000000 
00000000 
00000000 
00000000 


00880000 
00013000 
C4ESDAE5 
0000C70F 
FFFFFFFF 
00000000 
00000000 
00000000 


OOA2E3D6 
C4E4D4E5 
30C02008 
D4E5D6D3 
2008E5C3 
00000000 
00000000 
00000000 


D5E3C8D3 
D3F 10000 
E5C 3C2C3 
00003000 
C2C3D2F1 
E3C9D4C5 
00000000 
00000000 


200 1C4E4 
000030C0 
C2C3D2F3 
00000000 
00000000 
00000000 
00000000 
00000000 


00000000 
200 1C4E4 
D6D30000 
OFOFOEES 
00000000 
00000000 
00000000 
00000000 


E3C1D3E2 
D3F 10000 
E5C3C2C3 
00003000 
C2C3D2F 1 
00000000 
00000000 
00000000 


00000000 00000000 00000000 
00000000 00000000 00000000 
00000000 00000000 00000000 
00000000 00000000 00000000 
20000000 00000000 90000005 


E8400000 
30002001 
D2F 20000 
2001C4E4 
000030C0 
C3C1D9C4 
00000000 
00000000 


D4E5D6D3 
2008E5C3 
000030C0 
00000000 
00000000 
00000000 
00000000 
00000000 


00010000 
D4E5D6D3 
C70FOFOF 
FOFOO0000 
00000000 
00000000 
00000000 
00000000 


40400000 
30002001 
D2F20000 
2001C4E4 
000030C0 
00000000 
00000000 
00000000 


QN0000N000 


00000000 
00000000 
00000000 
ooo0cejs 


001F0005 
C4E4D4E5 
D9C5D7D6 
D4E5D3F1 
2008E5C3 
00000502 
00000000 
00000000 


00003000 
C2C3D2F1 
2008E5C3 
00000000 
00000000 
00000000 
00000000 
00000000 


05030000 
0000C70F 
ODESFOFO 
00070001 
00000000 
00000000 
00000000 
00000000 


001F0005 
C4E4D4ES5 
EBD9E3D6 
D4E5D3F1 
2008E5C3 
00000000 
00000000 
00000000 


00000000 


Od ded 


00000000 
00000000 
00000900 

2000000 


30002001 
D3F20000 
DIE34040 
00003000 
C2C3D2F2 
00050004 
00000000 
00000000 


2001C4E4 
000030C0 
C2C3D2F4 
00000000 
00000000 
00000000 
00000000 
00000000 


05000000 
OFOFOCES5 
00000007 
30002001 
00000000 
00000000 
00000000 
oo00C000 


30002001 
D3F20000 
C4C1E3c5 
00003000 
C2C3D2F2 
00000000 
00000000 
00000000 


00000000 


OO edad 


00000000 
00000000 
00000000 
o0000cnn0 


C4E4D4E5 
30C 

000000 1F 
2001C4E4 
QO00E2C1 
FFFFFFFF 
00000000 
00000000 


D4ESD3F1 
2008E5C3 
00000000 
00000000 
00000000 
00000000 
00000000 
00000000 


C70FOFOF 
FOFO0000 
00013000 
C4EAD4ES 
00000000 
00000000 
00000000 
00000000 


C4EAD4SES 
30C02008 
OOOO0001F 
200 1C4E4 
OOOOFFFF 


00000000 
00000000 


00000000 
00000000 


Second block of 
index ‘PAYROLL’ 


Volume control 
block 


Generation index 


Third block of 
index ‘PAYROLL’ 


0000000 
000000 Unused block of 


aen0000/N 


SYSCTLG 
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The data portion of each block begins with a 16-bit binary number that tells how 
many bytes of the block are used (including the two bytes of this number). The 
catalog entries begin immediately thereafter. These entries are described in detail 
in the chapter ‘“‘Data Areas.” 


The first entry of the first block is always the volume index control entry (VICE). 
The type of each entry can be determined from the byte at offset 11 of the entry; 
the type codes are described under the field TYPE on page 69. 


Environment Record 


Some error conditions cause an environment record to be written, whenever 
possible, to the last block of SYSCTLG. The environment record is written when a 
non-locate function is requested and the exceptional return code is 8 or 28. Here’s 
how you can dump the catalog and examine this re¢ord to see what happened: 


1. Reproduce the failure, but this time reservé the data set SYSCTLG for your 
exclusive use, so that no other task’can destroy the environment record before 
you can dump it. Do this by adding or modifying your JCL statements to include 
a DD statement for SYSCTLG with DISP=OLD. 


* et $F oRGr ass 
vast YdOS 


- rq tr a 


2. Add a step to your job to dump SYSCTLG. Follow the instructions under 
“SYSCTLG Dump.” 


3. Look at the VICE, which begins at offset two of the first physical block of the 
catalog. (Remember to allow for the key.) Field VCLSTBLK (offset 12 bytes in 
the VICE) contains the TTR for the last block in SYSCTLG. This block contains 
the environment record. 


4. Compute the absolute track address by using the cylinder-head numbers 
supplied for the first block and the TTR. TT is the relative track from the first 
block; R is the record number for that track. 


5. The fields of the environment record are described in “Environment Record 
(EREC DSECT),”’ on page 66. The description for each field relates this 
information to other data areas. 


The field ERMODMAP contains seven bits that show which modules have been 
entered. [GC0002F and IGGOCLCO are always entered; there are no bit switches for 
those modules. 


As an example, if ERMODMAP equals X‘66’, then modules IGC0002F, IGGOCLCO, 
IGGOCLC2, IGGOCLC3, IGGOCLC6, and IGGOCLC7 were entered during the request 
that caused the environment record to be written. This is the sequence of modules 
that normally occurs with a request for BLDX. 


Note: The environment record is not written for any error associated with a 
“‘catalog-full” condition. 


Module Selection Charts 


Figure 15 can help you determine which modules of the catalog management 
routines are involved in any given situation. The figure consists of several charts, 
which are modified reductions of Figure 10, found on page 26 Each chart shows 
the path through the catalog management routines for the functions noted on that 
chart. Figure 10 does not show the preprocessing done by the Controller. The 
blocks that are used are shaded. The specific path is shown by a bold arrow. 
Always enter module IGGOCLCO, which is the first load of the OS/VS catalog (upper 
left), then move down and to the right. 
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Page number references for flowcharts and module discussions are: 


Page 
Module Name Number 
IGC0002F, Controller I 32 
IGCO0002F, Controller II 34 
IGGOCLCA 36 
IGGOCLCB 38 
IGGOCLCO 40 
IGGOCLC1 42 
IGGOCLC2 44 
IGGOCLC3 46 
IGGOCLC4 48 
IGGOCLCS 50 
IGGOCLC6 52 
IGGOCLC7 54 
IGC0002H 56 
IGGOCLF2 58 


Bale ea BLDG, Locate Relative GDG Name 
Locate Simple or Quaiifted Name , with an Alias 


7 | 


a ws tt 


CATBX 


oe ey a 
IGGOCLC1 : 
wee 


Locate Ralative GDG Name Locate Qualified Name 
with an Alias 
iscocics 


Catalog Function with VCB Processing 
Required, GDG Empty Option Required, 
LNKX and BLDA or blocks to delete (UCATDX) 


CAT, UNCAT, RECAT, UCATDX 


cma 


| Figure 15. Correlating Functions to Modules of Catalog Management 
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Glossary 


This glossary contains definitions of words and acronyms that 
are used in this publication. Other data processing definitions 
can be found in Data Processing Glossary, GC20-1699. 


alias: An alternative name for a data set. Only the high-level 
name of a qualified data set name may have an alias. 


CAMLST: An Assembler language macro instruction that 
produces the parameter list for catalog management. 


catalog: (noun) The collection of all data set indexes maintained 
by data management. (verb) To include the volume 
identification of a data set in the catalog. 


CATALOG: An Assembler language macro instruction used to 
invoke the catalog management routines. 


cataloged data set: A data set that is represented in an index or 
hierarchy of indexes that provides the means for locating the 
data set. 


communication vector table (CVT): An operating system control 
block that provides the address of information in the nucleus to 
non-resident routines. 


connected: The property of a control volume that allows it to be 
found by searching another control volume. 


control volume (CVOL): A volume that contains one or more of 
the indexes of the catalog. 


data control block (DCB): An operating system control block that 
describes the current use of the data set. 


data extent block (DEB): A control block that describes the 
physical attributes of the data set. 


data set: The major unit of data storage and retrieval in the 
operating system. 


data set control block (DSCB): A label for a data set on a direct 
storage volume. 


data set name: An identifier that unambiguously names a data 
set. 


data set pointer entry (DSPE): A catalog entry that identifies the 
volume on which a named data set resides. 


dequeue: To remove a request for a resource from a list of 
requests. 


enqueue: To build a list of requests for a named resource. 

entry: A logical record of the catalog, data set SYSCTLG. 
environment record: A 256-byte record that is written when the 
catalog management routines discover an error. This record, 
which contains significant data that is present at the time of the 
error, is written to the last block of data set SYSCTLG for later 
analysis. 


generation: One member of a generation data group. 


generation data group (GDG): A collection of historically related 
data sets. 


generation index: An index of the catalog that identifies the 
generations of a generation data group. 


generation index pointer entry (GIPE): A catalog entry that 
identifies a generation index. 


high-level name: The first component of a qualified name. This 
name is found in a volume index of the catalog. 


index: A table in the catalog structure that is used to locate data 
sets. 


INDEX: An Assembler language macro instruction used to 
invoke the catalog management routines. 


index control entry (ICE): The first entry of each index of the 
catalog. This entry contains all control information about the 
index. 


index link entry (ILE): The last entry of each block of the catalog, 
used to link blocks of one index together in a chain. 


index pointer entry (IPE): A catalog entry that attaches a 
lower-level index to the index in which it is found. 


level: A conceptual relationship between indexes of the catalog. 

The index corresponding to the simple name of a data set is said 
to be the lowest level; the first component of a qualifier name is 
said to correspond to the highest-level index. 


locate: Pertaining to functions that do not change the status of 
the catalog; that is, read-only operations are performed on the 
catalog. 


LOCATE: An Assembler language macro instruction used to 
invoke the catalog management routines. 


must-complete: A facility of the operating system that ensures 
integrity whenever system resources are manipulated to modify 
information that is critical to the continued operation of the 
system. 


non-locate: Pertaining to functions that change the status of the 
catalog; that is, write operations are performed on the catalog. 


partitioned data set directory: The portion of a partitioned data 
set that provides a means of locating any of the members of the 
data set. 


qualified name: A data set name consisting of a string of names 
separated by periods; for example, ““TREE.FRUIT.APPLE” is a 
qualified name. 


qualifier: Each component name in a qualified name other than 
the rightmost name. For example, ‘““TREE” and “FRUIT” are 
qualifiers in “TREE.FRUIT.APPLE”. 


relative track address (TTR): A direct-access device address, 
expressed as a displacement in a data set. This address has the 
form TTR, where TT represents two hexadecimal digits 
specifying the track relative to the beginning of the data set, and 
R is one hexadecimal digit specifying the record on that track. 


resource: Any facility of the computing system or operating 
system required by a job or task, including main storage, 
input/output devices, the central processing unit, data sets, and 
control processing systems. Three unique resources are used by 
catalog management routines: the volume index, high-level 
name, and the volume index control entry (VICE). 


ripple: Displacing data from one block of a chain to the next, 
due to modification of data in a preceding block. 
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simple name: The rightmost component of a qualified name. For 
example, ““APPLE”’ is the simple name in 
“TREE.FRUIT.APPLE”’. The simple name corresponds to the 
lowest index level for the data set name. 


supervisor request block (SVRB): An operating system control 
block containing program status information and general 
register contents. 


SYSCTLG: The data set name of the catalog. 


system residence volume: The volume on which the nucleus of the 
operating system and the highest level of the catalog are located. 


task control block (TCB): An operating system control block that 
contains information and pointers associated with the task in 
progress. 

transient area: An area of main storage contained within the 
operating system nucleus where supervisor routines may be 
temporarily loaded for execution. 


true name: The high-level qualifier to which an alias is related. 
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uncatalog: To remove the volume identification of a data set 
from the catalog. 


volume control block (VCB): A block of the catalog that identifies 
as many as 20 volumes containing one data set. 


volume control block pointer entry (VCBPE): A catalog entry that 
identifies a VCB for a named data set. 


volume index: The highest level of index in the catalog structure. 
Entries in the volume index point to all lower indexes and 
simple names. 


volume index control entry (VICE): The first entry in the volume 
index. The VICE describes the volume index and controls space 
allocation in SYSCTLG. 


volume table of contents (VTOC): A table associated with a direct 
access volume that describes each data set on that volume and 
identifies all available space on the volume. 


Index 


The entries in this index are shown as they appear in the text 
of the book, that is, capitalized words are capitalized in text, 
lowercase words are lowercase in text, etc. When more than 
one reference is given for an entry, the primary reference is 
listed first. 


A 
ABEND dump ..................468. 73 
absolute name 

complemented ............6. 4808-4 14 

generation data group ..........4.2.2.24.2. 13 
absolute track addresses to relative, conversion ..... 28 
ADDING data field ..........02.2.22.222. 71 
BCUINS-CNtHES a's. oak Gah, (eS Ce ee el we ee 52 
address conversion, track ........2..4.. ... 28 
aids for diagnosing ........... 2. eee eee 73 
alias 

MAING iy, 9, ee Ga A de. ae ee ee ce @ SE 13 

MUMDEE OF 4a 4cf6> eS. Bo Age ee es Je ae ES 13 

PESOIMUION A ae ce Se, SR ae SE es we eS Oe BEES 42 
Alias Entry (AE)... .......2...08428.4 ... 62 
ALIASNAM data field ............0.20422. 69 
AMASPZAP, use with catalog management. ...... 74 
B 
BALREGS data field ...............428. 72 
base register a. wa ae a eS Rw RRO Se He ES 29 
BASESAVE datafield ............2..2. 72 
BLDA function .............2..084 16 
BLDENTRY routine in IGGOCLC4 .......... 49 
BLDG function ............02...08248-. 16 
BLDL macro instruction 

listed in program organization ........4... 28 
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